@erseco/code-snippets-client 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# Code Snippets Client
+
+[![CI](https://github.com/erseco/code-snippets-client/actions/workflows/ci.yml/badge.svg)](https://github.com/erseco/code-snippets-client/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@erseco/code-snippets-client)](https://www.npmjs.com/package/@erseco/code-snippets-client)
+[![Publish](https://github.com/erseco/code-snippets-client/actions/workflows/publish.yml/badge.svg)](https://github.com/erseco/code-snippets-client/actions/workflows/publish.yml)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
+
+A TypeScript client and CLI for the WordPress [Code Snippets](https://wordpress.org/plugins/code-snippets/)
+REST API. List, create, update, activate, deactivate and delete snippets from Node.js,
+using application passwords, WordPress login, existing sessions or CAS forms.
+An independent, unofficial project. Not the WPCode plugin.
+
+## Install
+
+Requires **Node.js 22.14 or later**. Ships as ESM with compiled JavaScript and types.
+
+```sh
+npm install @erseco/code-snippets-client
+```
+
+```ts
+import { CodeSnippetsClient } from "@erseco/code-snippets-client";
+
+const client = new CodeSnippetsClient({
+  baseUrl: "https://wordpress.example",
+  auth: {
+    type: "application-password",
+    username: process.env.WP_USERNAME!,
+    password: process.env.WP_PASSWORD!,
+  },
+});
+
+const snippets = await client.list();
+const snippet = await client.create({
+  name: "Demo",
+  code: "// PHP without <?php",
+});
+await client.update(snippet.id, { code: "// Updated code" });
+// When you are ready to run it:
+await client.activate(snippet.id);
+```
+
+New snippets are **inactive by default**. Updates preserve unspecified fields and
+remote activation state. `single-use` snippets are never implicitly rearmed.
+The library does not load `.env`, write backups or run Git commands.
+
+## CLI for developers and agents
+
+The CLI uses the same client. It only reads the explicitly selected `.env` file;
+existing environment variables take precedence. No global installation needed.
+
+```sh
+npx wp-code-snippets list --env-file .env
+npx wp-code-snippets diff 42 --file snippets/demo.php --env-file .env
+npx wp-code-snippets push 42 --file snippets/demo.php --env-file .env --yes
+npx wp-code-snippets create --name Demo --file snippets/demo.php --env-file .env --yes
+```
+
+Every write requires `--yes`; agents obtain authorization in the conversation.
+`--dry-run` previews the supplied fields without connecting to WordPress. It does
+not verify permissions, PHP syntax or remote conflicts. `diff` returns both code
+versions and whether they match. Output is JSON except for `pull` and help.
+Errors go to stderr and produce a nonzero exit code.
+
+[API and CLI reference](docs/api.md) · [Authentication and CAS](docs/authentication.md) ·
+[Architecture and limits](docs/architecture.md) · [Development and releases](docs/development.md)
+
+## Test
+
+```sh
+npm ci
+npm run check
+npm run test:package
+npm run test:integration  # Docker required; starts and stops disposable WordPress
+```
+
+CI runs on Linux, Windows and macOS. WordPress integration runs on Linux, pinned
+to **WordPress 7.1, PHP 8.3 and Code Snippets 3.10.2**. CAS tests use a local HTTP
+form/ticket/callback simulator; they do not certify every Apereo deployment or MFA.
+
+Licensed under GPL-3.0-only. See [LICENSE](LICENSE).

package/dist/auth.d.ts

@@ -0,0 +1,3 @@
+import { Session } from "./session.js";
+import type { Authentication } from "./types.js";
+export declare function authenticate(session: Session, auth: Authentication, base: URL, admin: URL, allowHttp: boolean): Promise<Headers>;

package/dist/auth.js

@@ -0,0 +1,76 @@
+import { load } from "cheerio/slim";
+import { CodeSnippetsError } from "./errors.js";
+import { checkedUrl } from "./session.js";
+/** Submit a form on its expected origin, preserving hidden CAS fields. */
+async function submitLogin(session, response, expected, fields, allowHttp) {
+    if (!response.ok || new URL(response.url).origin !== expected.origin)
+        throw new CodeSnippetsError("AUTH", "Login form not found on the configured origin");
+    const $ = load(await response.text());
+    const form = $('input[type="password"]').first().closest("form");
+    if (!form.length)
+        throw new CodeSnippetsError("AUTH", "Password form missing; interactive authentication may be required");
+    const action = checkedUrl(new URL(form.attr("action") || response.url, response.url).href, allowHttp);
+    if (action.origin !== expected.origin)
+        throw new CodeSnippetsError("AUTH", "Cross-origin login form refused");
+    const data = new URLSearchParams();
+    form.find("input[name]").each((_, element) => {
+        const field = $(element);
+        if (field.attr("type") === "hidden" && !field.is("[disabled]"))
+            data.set(field.attr("name"), field.attr("value") ?? "");
+    });
+    for (const [name, value] of Object.entries(fields))
+        data.set(name, value);
+    const result = await session.request(action, { method: "POST", body: data });
+    if (!result.ok) {
+        await result.body?.cancel();
+        throw new CodeSnippetsError("AUTH", "Login rejected", result.status);
+    }
+    await result.body?.cancel();
+}
+export async function authenticate(session, auth, base, admin, allowHttp) {
+    if (auth.type === "application-password") {
+        return new Headers({
+            authorization: `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString("base64")}`,
+        });
+    }
+    if (auth.type === "session")
+        return new Headers({ cookie: auth.cookie, "x-wp-nonce": auth.nonce });
+    const adminPage = new URL("admin.php?page=add-snippet", admin);
+    if (auth.type === "wordpress") {
+        const login = checkedUrl(auth.loginUrl ?? new URL("wp-login.php", base).href, allowHttp);
+        if (login.origin !== base.origin)
+            throw new CodeSnippetsError("CONFIG", "WordPress login must use the site origin");
+        await submitLogin(session, await session.request(login), login, {
+            log: auth.username,
+            pwd: auth.password,
+            "wp-submit": "Log In",
+            redirect_to: adminPage.href,
+            testcookie: "1",
+        }, allowHttp);
+    }
+    else {
+        const cas = checkedUrl(auth.loginUrl, allowHttp);
+        let entry = checkedUrl(auth.entryUrl ?? new URL("wp-login.php", base).href, allowHttp);
+        if (entry.origin !== base.origin)
+            throw new CodeSnippetsError("CONFIG", "CAS entry must use the WordPress origin");
+        if (auth.serviceUrl) {
+            const service = checkedUrl(auth.serviceUrl, allowHttp);
+            if (service.origin !== base.origin)
+                throw new CodeSnippetsError("CONFIG", "CAS service must use the WordPress origin");
+            cas.searchParams.set("service", service.href);
+            entry = cas;
+        }
+        await submitLogin(session, await session.request(entry), cas, { username: auth.username, password: auth.password, _eventId: "submit" }, allowHttp);
+    }
+    const page = await session.request(adminPage);
+    if (!page.ok || new URL(page.url).origin !== base.origin) {
+        await page.body?.cancel();
+        throw new CodeSnippetsError("AUTH", "WordPress session not established", page.status);
+    }
+    const html = await page.text();
+    const nonce = /createNonceMiddleware\s*\(\s*["']([a-f0-9]{10})["']/.exec(html)?.[1] ??
+        /["']nonce["']\s*:\s*["']([a-f0-9]{10})["']/.exec(html)?.[1];
+    if (!nonce)
+        throw new CodeSnippetsError("AUTH", "REST nonce missing; check login and snippet permissions");
+    return new Headers({ "x-wp-nonce": nonce });
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+import { CodeSnippetsError } from "./errors.js";
+try {
+    const result = await runCli(process.argv.slice(2));
+    process.stdout.write(typeof result === "string"
+        ? result
+        : JSON.stringify(result, null, 2) + "\n");
+}
+catch (error) {
+    const safe = error instanceof CodeSnippetsError
+        ? { code: error.code, message: error.message, status: error.status }
+        : {
+            code: "CLI",
+            message: "Invalid arguments, input file or environment; use --help",
+        };
+    process.stderr.write(JSON.stringify({ error: safe }) + "\n");
+    process.exitCode = 1;
+}

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+import type { ClientOptions } from "./types.js";
+export declare const help = "wp-code-snippets <command> [id] [options]\n\nCommands: list, get, create, update, push, pull, diff, activate, deactivate, delete, restore\nOptions:\n  --env-file PATH    Explicit .env (never searched automatically)\n  --file PATH        PHP source for create/update/push/diff\n  --input PATH       JSON snippet fields for create/update (use - for stdin)\n  --output PATH      Save pull output without overwriting an existing file\n  --name TEXT       Snippet name for create/update\n  --scope TEXT      Snippet scope\n  --priority N      Execution priority\n  --enable          Explicit activation on create/update\n  --disable         Explicit deactivation on create/update\n  --yes             Required for every remote write\n  --dry-run         Return intended fields without writing\n  --json            JSON output (default; pull writes raw code)\n  --help            Show this help\n\nConfiguration: WP_URL, WP_AUTH=application-password|wordpress|cas|session,\nWP_USERNAME, WP_PASSWORD, WP_NETWORK=true|false, WP_ADMIN_URL,\nCAS_LOGIN_URL, CAS_SERVICE_URL, CAS_ENTRY_URL, WP_COOKIE, WP_NONCE.\nWP_ALLOW_HTTP=true is for disposable local tests only.\n";
+export declare function clientOptions(env: Record<string, string | undefined>): ClientOptions;
+export declare function normalizePhp(code: string): string;
+export declare function runCli(args: string[], environment?: Record<string, string | undefined>): Promise<unknown>;

package/dist/cli.js

@@ -0,0 +1,219 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { parseArgs, parseEnv } from "node:util";
+import { CodeSnippetsClient, validateSnippetInput } from "./client.js";
+import { CodeSnippetsError } from "./errors.js";
+export const help = `wp-code-snippets <command> [id] [options]
+
+Commands: list, get, create, update, push, pull, diff, activate, deactivate, delete, restore
+Options:
+  --env-file PATH    Explicit .env (never searched automatically)
+  --file PATH        PHP source for create/update/push/diff
+  --input PATH       JSON snippet fields for create/update (use - for stdin)
+  --output PATH      Save pull output without overwriting an existing file
+  --name TEXT       Snippet name for create/update
+  --scope TEXT      Snippet scope
+  --priority N      Execution priority
+  --enable          Explicit activation on create/update
+  --disable         Explicit deactivation on create/update
+  --yes             Required for every remote write
+  --dry-run         Return intended fields without writing
+  --json            JSON output (default; pull writes raw code)
+  --help            Show this help
+
+Configuration: WP_URL, WP_AUTH=application-password|wordpress|cas|session,
+WP_USERNAME, WP_PASSWORD, WP_NETWORK=true|false, WP_ADMIN_URL,
+CAS_LOGIN_URL, CAS_SERVICE_URL, CAS_ENTRY_URL, WP_COOKIE, WP_NONCE.
+WP_ALLOW_HTTP=true is for disposable local tests only.
+`;
+function boolean(env, key) {
+    if (env[key] !== undefined && !["true", "false"].includes(env[key]))
+        throw new CodeSnippetsError("CONFIG", `${key} must be true or false`);
+    return env[key] === "true";
+}
+export function clientOptions(env) {
+    const type = env.WP_AUTH ?? "application-password";
+    const credentials = {
+        username: env.WP_USERNAME ?? "",
+        password: env.WP_PASSWORD ?? "",
+    };
+    let auth;
+    if (type === "application-password" || type === "wordpress")
+        auth = { type, ...credentials };
+    else if (type === "session")
+        auth = { type, cookie: env.WP_COOKIE ?? "", nonce: env.WP_NONCE ?? "" };
+    else if (type === "cas")
+        auth = {
+            type,
+            ...credentials,
+            loginUrl: env.CAS_LOGIN_URL ?? "",
+            ...(env.CAS_SERVICE_URL ? { serviceUrl: env.CAS_SERVICE_URL } : {}),
+            ...(env.CAS_ENTRY_URL ? { entryUrl: env.CAS_ENTRY_URL } : {}),
+        };
+    else
+        throw new CodeSnippetsError("CONFIG", "Unsupported WP_AUTH");
+    return {
+        baseUrl: env.WP_URL ?? "",
+        auth,
+        network: boolean(env, "WP_NETWORK"),
+        allowInsecureHttp: boolean(env, "WP_ALLOW_HTTP"),
+        ...(env.WP_ADMIN_URL ? { adminUrl: env.WP_ADMIN_URL } : {}),
+    };
+}
+export function normalizePhp(code) {
+    return code
+        .replace(/\r\n/g, "\n")
+        .replace(/^\uFEFF?\s*<\?php(?:\s|$)/, "")
+        .replace(/\?>\s*$/, "");
+}
+export async function runCli(args, environment = process.env) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            "env-file": { type: "string" },
+            file: { type: "string" },
+            input: { type: "string" },
+            output: { type: "string" },
+            name: { type: "string" },
+            scope: { type: "string" },
+            priority: { type: "string" },
+            enable: { type: "boolean" },
+            disable: { type: "boolean" },
+            yes: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            json: { type: "boolean" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help || !positionals.length)
+        return help;
+    const [command, idText, ...extra] = positionals;
+    const commands = [
+        "list",
+        "get",
+        "create",
+        "update",
+        "push",
+        "pull",
+        "diff",
+        "activate",
+        "deactivate",
+        "delete",
+        "restore",
+    ];
+    if (!commands.includes(command) || extra.length)
+        throw new CodeSnippetsError("VALIDATION", "Invalid command or arguments");
+    const needsId = !["list", "create"].includes(command);
+    const id = Number(idText);
+    if (needsId ? !Number.isSafeInteger(id) || id <= 0 : idText !== undefined)
+        throw new CodeSnippetsError("VALIDATION", "Provide an ID only for commands operating on an existing snippet");
+    const mutation = !["list", "get", "pull", "diff"].includes(command);
+    if (mutation && !values.yes && !values["dry-run"])
+        throw new CodeSnippetsError("VALIDATION", "Remote writes require --yes after reviewing the intended change");
+    if (values.enable && values.disable)
+        throw new CodeSnippetsError("VALIDATION", "--enable and --disable are mutually exclusive");
+    const writeFields = ["create", "update", "push"].includes(command);
+    if (!writeFields &&
+        (values.input ||
+            values.name ||
+            values.scope ||
+            values.priority ||
+            values.enable ||
+            values.disable))
+        throw new CodeSnippetsError("VALIDATION", "Snippet fields are only valid for create/update/push");
+    if (values.file && !writeFields && command !== "diff")
+        throw new CodeSnippetsError("VALIDATION", "--file is only valid for create/update/push/diff");
+    if (values.output && command !== "pull")
+        throw new CodeSnippetsError("VALIDATION", "--output is only valid for pull");
+    if (values["dry-run"] && !mutation)
+        throw new CodeSnippetsError("VALIDATION", "--dry-run is only valid for remote writes");
+    const env = values["env-file"]
+        ? {
+            ...parseEnv(await readFile(values["env-file"], "utf8")),
+            ...environment,
+        }
+        : environment;
+    const client = new CodeSnippetsClient(clientOptions(env));
+    let input = {};
+    if (values.input) {
+        let text;
+        if (values.input === "-") {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(Buffer.from(chunk));
+            text = Buffer.concat(chunks).toString("utf8");
+        }
+        else
+            text = await readFile(values.input, "utf8");
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new CodeSnippetsError("VALIDATION", "--input must contain a JSON object");
+        input = parsed;
+    }
+    if (values.file)
+        input.code = normalizePhp(await readFile(values.file, "utf8"));
+    if (values.name !== undefined)
+        input.name = values.name;
+    if (values.scope !== undefined)
+        input.scope = values.scope;
+    if (values.priority !== undefined)
+        input.priority = Number(values.priority);
+    if (values.enable || values.disable)
+        input.active = !!values.enable;
+    if (writeFields) {
+        validateSnippetInput(input);
+        if (command === "create" &&
+            (!input.name?.trim() || typeof input.code !== "string"))
+            throw new CodeSnippetsError("VALIDATION", "A name and code are required");
+        if (command !== "create" && !Object.keys(input).length)
+            throw new CodeSnippetsError("VALIDATION", "No changes supplied");
+    }
+    if (values["dry-run"])
+        return {
+            command,
+            id: needsId ? id : undefined,
+            changes: input,
+            applied: false,
+        };
+    switch (command) {
+        case "list":
+            return client.list();
+        case "get":
+            return client.get(id);
+        case "create":
+            return client.create(input);
+        case "update":
+        case "push":
+            return client.update(id, input);
+        case "activate":
+            return client.activate(id);
+        case "deactivate":
+            return client.deactivate(id);
+        case "delete":
+            return client.delete(id);
+        case "restore":
+            return client.restore(id);
+        case "diff": {
+            if (!values.file)
+                throw new CodeSnippetsError("VALIDATION", "diff requires --file");
+            const remote = await client.get(id);
+            return {
+                id,
+                equal: remote.code === input.code,
+                remote: remote.code,
+                local: input.code,
+            };
+        }
+        case "pull": {
+            const remote = await client.get(id);
+            if (!values.output)
+                return remote.code;
+            await writeFile(values.output, remote.code, {
+                encoding: "utf8",
+                flag: "wx",
+            });
+            return { id, output: values.output };
+        }
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { ClientOptions, ListOptions, Snippet, SnippetInput } from "./types.js";
+export declare function validateSnippetInput(input: Partial<SnippetInput>): void;
+export declare class CodeSnippetsClient {
+    private readonly options;
+    private readonly base;
+    private readonly admin;
+    private readonly session;
+    private loginPromise;
+    constructor(options: ClientOptions);
+    /** Initialize authentication; API methods initialize it automatically. */
+    login(): Promise<void>;
+    private headers;
+    private request;
+    /** Without explicit pagination, the plugin returns the entire collection. */
+    list(options?: ListOptions): Promise<Snippet[]>;
+    get(id: number): Promise<Snippet>;
+    create(input: SnippetInput): Promise<Snippet>;
+    update(id: number, changes: Partial<SnippetInput>): Promise<Snippet>;
+    private checkState;
+    activate(id: number): Promise<Snippet>;
+    deactivate(id: number): Promise<Snippet>;
+    /** The plugin moves to trash first; deleting an already trashed snippet is permanent. */
+    delete(id: number): Promise<Snippet | null>;
+    restore(id: number): Promise<Snippet>;
+}

package/dist/client.js

@@ -0,0 +1,233 @@
+import { authenticate } from "./auth.js";
+import { CodeSnippetsError } from "./errors.js";
+import { checkedUrl, Session } from "./session.js";
+const fields = [
+    "name",
+    "code",
+    "desc",
+    "scope",
+    "priority",
+    "tags",
+    "active",
+    "shared_network",
+    "condition_id",
+    "locked",
+];
+function idPath(id) {
+    if (!Number.isSafeInteger(id) || id <= 0)
+        throw new CodeSnippetsError("VALIDATION", "Snippet ID must be a positive safe integer");
+    return String(id);
+}
+export function validateSnippetInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new CodeSnippetsError("VALIDATION", "Expected snippet fields");
+    for (const [key, value] of Object.entries(input)) {
+        if (!fields.includes(key))
+            throw new CodeSnippetsError("VALIDATION", "Unknown snippet field");
+        const valid = ["name", "code", "desc", "scope"].includes(key)
+            ? typeof value === "string"
+            : ["active", "shared_network", "locked"].includes(key)
+                ? typeof value === "boolean"
+                : key === "tags"
+                    ? Array.isArray(value) && value.every((v) => typeof v === "string")
+                    : Number.isSafeInteger(value) && Number(value) >= 0;
+        if (!valid)
+            throw new CodeSnippetsError("VALIDATION", "Invalid snippet field value");
+    }
+}
+function snippet(value) {
+    if (!value || typeof value !== "object")
+        throw new CodeSnippetsError("RESPONSE", "Expected a snippet object");
+    const s = value;
+    if (!Number.isSafeInteger(s.id) ||
+        Number(s.id) <= 0 ||
+        typeof s.name !== "string" ||
+        typeof s.code !== "string" ||
+        typeof s.active !== "boolean" ||
+        typeof s.scope !== "string" ||
+        typeof s.desc !== "string" ||
+        typeof s.network !== "boolean" ||
+        typeof s.trashed !== "boolean" ||
+        !Number.isSafeInteger(s.priority) ||
+        !Array.isArray(s.tags) ||
+        !s.tags.every((t) => typeof t === "string")) {
+        throw new CodeSnippetsError("RESPONSE", "Invalid snippet response");
+    }
+    return { ...s, code: s.code.replace(/\r\n/g, "\n") };
+}
+export class CodeSnippetsClient {
+    options;
+    base;
+    admin;
+    session;
+    loginPromise;
+    constructor(options) {
+        this.options = options;
+        const allowHttp = options.allowInsecureHttp ?? false;
+        this.base = checkedUrl(options.baseUrl, allowHttp);
+        if (this.base.search)
+            throw new CodeSnippetsError("CONFIG", "baseUrl must be a site URL without query parameters");
+        this.base.pathname = this.base.pathname.replace(/\/$/, "") + "/";
+        this.admin = checkedUrl(options.adminUrl ??
+            new URL(options.network ? "wp-admin/network/" : "wp-admin/", this.base)
+                .href, allowHttp);
+        this.admin.pathname = this.admin.pathname.replace(/\/$/, "") + "/";
+        if (this.admin.origin !== this.base.origin)
+            throw new CodeSnippetsError("CONFIG", "Admin URL must use the site origin");
+        const timeout = options.timeoutMs ?? 30000;
+        if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 2147483647)
+            throw new CodeSnippetsError("CONFIG", "Invalid timeout");
+        const auth = options.auth;
+        if (!auth ||
+            !["wordpress", "cas", "application-password", "session"].includes(auth.type))
+            throw new CodeSnippetsError("CONFIG", "Unsupported authentication type");
+        if (auth.type === "session"
+            ? !auth.cookie || !auth.nonce
+            : !auth.username || !auth.password)
+            throw new CodeSnippetsError("CONFIG", "Authentication credentials are required");
+        const origins = new Set([this.base.origin]);
+        if (auth.type === "cas")
+            origins.add(checkedUrl(auth.loginUrl, allowHttp).origin);
+        this.session = new Session(origins, timeout, allowHttp);
+    }
+    /** Initialize authentication; API methods initialize it automatically. */
+    async login() {
+        await this.headers();
+    }
+    headers() {
+        this.loginPromise ??= authenticate(this.session, this.options.auth, this.base, this.admin, this.options.allowInsecureHttp ?? false).catch((error) => {
+            this.loginPromise = undefined;
+            throw error;
+        });
+        return this.loginPromise;
+    }
+    async request(path, method = "GET", body, query = {}) {
+        const url = new URL(this.base);
+        url.searchParams.set("rest_route", `/code-snippets/v1/snippets${path ? "/" + path : ""}`);
+        url.searchParams.set("network", String(this.options.network ?? false));
+        for (const [key, value] of Object.entries(query))
+            url.searchParams.set(key, value);
+        const headers = new Headers(await this.headers());
+        headers.set("accept", "application/json");
+        if (body !== undefined)
+            headers.set("content-type", "application/json");
+        const response = await this.session.request(url, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        }, false);
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new CodeSnippetsError(response.status === 401 || response.status === 403 ? "AUTH" : "HTTP", `WordPress request failed (HTTP ${response.status})`, response.status);
+        }
+        if (response.status === 204)
+            return null;
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new CodeSnippetsError("RESPONSE", "Expected JSON from WordPress; check the site URL and session");
+        }
+    }
+    /** Without explicit pagination, the plugin returns the entire collection. */
+    async list(options = {}) {
+        const query = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (key === "page" || key === "perPage") {
+                if (!Number.isSafeInteger(value) ||
+                    Number(value) < 1 ||
+                    (key === "perPage" && Number(value) > 100))
+                    throw new CodeSnippetsError("VALIDATION", "Invalid pagination");
+                query[key === "perPage" ? "per_page" : key] = String(value);
+            }
+            else if (key === "search" && typeof value === "string")
+                query.search = value;
+            else if (key === "status" &&
+                ["all", "active", "inactive"].includes(String(value)))
+                query.status = String(value);
+            else
+                throw new CodeSnippetsError("VALIDATION", "Invalid list option");
+        }
+        const result = await this.request("", "GET", undefined, query);
+        if (!Array.isArray(result))
+            throw new CodeSnippetsError("RESPONSE", "Expected a snippet collection");
+        return result.map(snippet);
+    }
+    async get(id) {
+        return snippet(await this.request(idPath(id)));
+    }
+    async create(input) {
+        validateSnippetInput(input);
+        if (!input.name?.trim() || typeof input.code !== "string")
+            throw new CodeSnippetsError("VALIDATION", "A name and code are required");
+        const result = snippet(await this.request("", "POST", {
+            ...input,
+            active: input.active ?? false,
+            network: this.options.network ?? false,
+        }));
+        this.checkState(result, input.active ?? false, input.scope === "single-use");
+        return result;
+    }
+    async update(id, changes) {
+        idPath(id);
+        validateSnippetInput(changes);
+        if (!Object.keys(changes).length)
+            throw new CodeSnippetsError("VALIDATION", "No changes supplied");
+        const remote = await this.get(id);
+        const payload = {};
+        for (const field of fields)
+            if (remote[field] !== undefined)
+                payload[field] = remote[field];
+        Object.assign(payload, changes, { network: this.options.network ?? false });
+        const singleUse = remote.scope === "single-use" || payload.scope === "single-use";
+        if (singleUse && changes.active === undefined)
+            delete payload.active;
+        let result = snippet(await this.request(idPath(id), "POST", payload));
+        // Saving code can deactivate a valid snippet through redeclaration in that request.
+        // Never retry a single-use activation that may already have been consumed.
+        if (!singleUse &&
+            changes.active === undefined &&
+            remote.active &&
+            !result.active &&
+            !result.code_error) {
+            result = await this.activate(id);
+        }
+        this.checkState(result, changes.active ?? (singleUse ? undefined : remote.active), singleUse);
+        return result;
+    }
+    checkState(result, expected, singleUse = false) {
+        if (result.code_error)
+            throw new CodeSnippetsError("STATE", `WordPress reported a code error for snippet ${result.id}`);
+        if (expected !== undefined &&
+            !(singleUse && expected) &&
+            result.active !== expected)
+            throw new CodeSnippetsError("STATE", `WordPress did not preserve the requested state of snippet ${result.id}`);
+    }
+    async activate(id) {
+        await this.request(`${idPath(id)}/activate`, "POST", {
+            network: this.options.network ?? false,
+        });
+        const result = await this.get(id);
+        this.checkState(result, true, result.scope === "single-use");
+        return result;
+    }
+    async deactivate(id) {
+        await this.request(`${idPath(id)}/deactivate`, "POST", {
+            network: this.options.network ?? false,
+        });
+        const result = await this.get(id);
+        this.checkState(result, false);
+        return result;
+    }
+    /** The plugin moves to trash first; deleting an already trashed snippet is permanent. */
+    async delete(id) {
+        const result = await this.request(idPath(id), "DELETE");
+        return result === null ? null : snippet(result);
+    }
+    async restore(id) {
+        await this.request(`${idPath(id)}/restore`, "POST", {
+            network: this.options.network ?? false,
+        });
+        return this.get(id);
+    }
+}