@erseco/code-snippets-client 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type ErrorCode = "CONFIG" | "AUTH" | "HTTP" | "NETWORK" | "RESPONSE" | "VALIDATION" | "STATE";
+/** Never includes HTTP bodies, cookies, passwords or ticket URLs. */
+export declare class CodeSnippetsError extends Error {
+    readonly code: ErrorCode;
+    readonly status?: number | undefined;
+    constructor(code: ErrorCode, message: string, status?: number | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+/** Never includes HTTP bodies, cookies, passwords or ticket URLs. */
+export class CodeSnippetsError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "CodeSnippetsError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { CodeSnippetsClient } from "./client.js";
+export { CodeSnippetsError } from "./errors.js";
+export type { ErrorCode } from "./errors.js";
+export type { Authentication, ClientOptions, ListOptions, Snippet, SnippetInput, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CodeSnippetsClient } from "./client.js";
+export { CodeSnippetsError } from "./errors.js";

package/dist/session.d.ts

@@ -0,0 +1,10 @@
+export declare function checkedUrl(value: string, allowHttp?: boolean): URL;
+/** In-memory session. Redirects may only visit configured origins. */
+export declare class Session {
+    private readonly origins;
+    private readonly timeoutMs;
+    private readonly allowHttp;
+    private readonly cookies;
+    constructor(origins: Set<string>, timeoutMs: number, allowHttp: boolean);
+    request(input: URL, init?: RequestInit, follow?: boolean): Promise<Response>;
+}

package/dist/session.js

@@ -0,0 +1,98 @@
+import { CookieJar } from "tough-cookie";
+import { CodeSnippetsError } from "./errors.js";
+export function checkedUrl(value, allowHttp = false) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new CodeSnippetsError("CONFIG", "Invalid URL");
+    }
+    if (url.username ||
+        url.password ||
+        url.hash ||
+        !["https:", ...(allowHttp ? ["http:"] : [])].includes(url.protocol)) {
+        throw new CodeSnippetsError("CONFIG", "Use HTTPS URLs without credentials or fragments");
+    }
+    return url;
+}
+/** In-memory session. Redirects may only visit configured origins. */
+export class Session {
+    origins;
+    timeoutMs;
+    allowHttp;
+    cookies = new CookieJar();
+    constructor(origins, timeoutMs, allowHttp) {
+        this.origins = origins;
+        this.timeoutMs = timeoutMs;
+        this.allowHttp = allowHttp;
+    }
+    async request(input, init = {}, follow = true) {
+        let url = input;
+        let method = init.method ?? "GET";
+        let body = init.body;
+        const headers = new Headers(init.headers);
+        const signal = AbortSignal.timeout(this.timeoutMs);
+        const explicitCookie = headers.get("cookie");
+        for (let step = 0; step <= 10; step++) {
+            checkedUrl(url.href, this.allowHttp);
+            if (!this.origins.has(url.origin))
+                throw new CodeSnippetsError("AUTH", "Redirect to an unconfigured origin refused");
+            const cookie = await this.cookies.getCookieString(url.href);
+            headers.delete("cookie");
+            const combinedCookie = [
+                cookie,
+                url.origin === input.origin ? explicitCookie : null,
+            ]
+                .filter(Boolean)
+                .join("; ");
+            if (combinedCookie)
+                headers.set("cookie", combinedCookie);
+            let response;
+            try {
+                response = await fetch(url, {
+                    ...init,
+                    method,
+                    body: body ?? null,
+                    headers,
+                    redirect: "manual",
+                    signal,
+                });
+            }
+            catch {
+                throw new CodeSnippetsError("NETWORK", "Request failed or timed out");
+            }
+            for (const value of response.headers.getSetCookie()) {
+                await this.cookies.setCookie(value, url.href, { ignoreError: true });
+            }
+            if (![301, 302, 303, 307, 308].includes(response.status))
+                return response;
+            const location = response.headers.get("location");
+            if (!follow || !location) {
+                await response.body?.cancel();
+                throw new CodeSnippetsError("AUTH", "Unexpected redirect; check the session and site URL", response.status);
+            }
+            const next = new URL(location, url);
+            // A 307/308 must never replay a password form to another origin.
+            if (next.origin !== url.origin) {
+                if (method !== "GET" &&
+                    method !== "HEAD" &&
+                    [307, 308].includes(response.status)) {
+                    await response.body?.cancel();
+                    throw new CodeSnippetsError("AUTH", "Cross-origin credential replay refused");
+                }
+                headers.delete("authorization");
+                headers.delete("x-wp-nonce");
+            }
+            if (response.status === 303 ||
+                ([301, 302].includes(response.status) && method === "POST")) {
+                method = "GET";
+                body = null;
+                headers.delete("content-type");
+            }
+            await response.body?.cancel();
+            url = next;
+        }
+        throw new CodeSnippetsError("AUTH", "Too many login redirects");
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/** Writable Code Snippets fields. IDs belong to the destination site. */
+export interface SnippetInput {
+    name: string;
+    code: string;
+    desc?: string;
+    scope?: string;
+    priority?: number;
+    tags?: string[];
+    active?: boolean;
+    shared_network?: boolean;
+    condition_id?: number;
+    locked?: boolean;
+}
+export interface Snippet extends SnippetInput {
+    id: number;
+    desc: string;
+    scope: string;
+    priority: number;
+    tags: string[];
+    active: boolean;
+    network: boolean;
+    trashed: boolean;
+    code_error?: unknown;
+}
+export type Authentication = {
+    type: "application-password";
+    username: string;
+    password: string;
+} | {
+    type: "wordpress";
+    username: string;
+    password: string;
+    loginUrl?: string;
+} | {
+    type: "cas";
+    username: string;
+    password: string;
+    loginUrl: string;
+    serviceUrl?: string;
+    entryUrl?: string;
+} | {
+    type: "session";
+    cookie: string;
+    nonce: string;
+};
+export interface ClientOptions {
+    baseUrl: string;
+    auth: Authentication;
+    network?: boolean;
+    adminUrl?: string;
+    timeoutMs?: number;
+    /** Explicit HTTP opt-in for disposable local environments. */
+    allowInsecureHttp?: boolean;
+}
+export interface ListOptions {
+    page?: number;
+    perPage?: number;
+    search?: string;
+    status?: "all" | "active" | "inactive";
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/api.md

@@ -0,0 +1,75 @@
+# API and CLI
+
+## Library
+
+All methods are asynchronous. `login()` initializes authentication headers or a
+session. Application password validity is checked on the first REST request.
+API methods initialize authentication automatically and share an in-progress login.
+
+| Method                                        | Result                                              |
+| --------------------------------------------- | --------------------------------------------------- |
+| `list({ page?, perPage?, search?, status? })` | `Snippet[]`                                         |
+| `get(id)`                                     | `Snippet`                                           |
+| `create({ name, code, ... })`                 | `Snippet`, inactive unless `active: true`           |
+| `update(id, changes)`                         | `Snippet`                                           |
+| `activate(id)` / `deactivate(id)`             | `Snippet` fetched after the operation               |
+| `delete(id)`                                  | Trashed snippet, or `null` after permanent deletion |
+| `restore(id)`                                 | `Snippet` fetched after restoration                 |
+
+IDs are positive integers local to each destination. Writable fields: `name`,
+`code`, `desc`, `scope`, `priority`, `tags`, `active`, `shared_network`, `condition_id`
+and `locked`. `network` belongs to the client configuration. Additional scopes and
+fields may require a specific plugin edition.
+
+Without explicit pagination, Code Snippets 3.10.2 returns the complete collection.
+With `page`/`perPage`, only that page is returned; there is no implicit pagination
+loop. `perPage` must be between 1 and 100. `status` accepts `all`, `active`, `inactive`.
+
+`update` reads remote state and preserves known fields you did not specify. Avoid
+concurrent updates of the same snippet: GET/POST is not a transaction. If saving an
+active snippet deactivates it without reporting a code error, the client attempts
+to restore activation once and verifies the result. When changing from/to
+`single-use`, `active` is omitted unless explicitly supplied, and execution is never
+retried. An explicit single-use activation may return `active: false` because the
+verification read already consumed the execution; verify its application-specific effect.
+
+`delete` follows plugin semantics: trash first, then permanently delete if already
+trashed. It never retries automatically.
+
+`CodeSnippetsError` provides `code`, `message` and an optional HTTP `status`.
+Codes: `CONFIG`, `VALIDATION`, `AUTH`, `HTTP`, `NETWORK`, `RESPONSE`, `STATE`.
+Errors do not include HTTP bodies, tickets, cookies or PHP source returned by the
+server. A network error during a write does not prove the write was not applied.
+
+## CLI
+
+`wp-code-snippets --help` lists all arguments. The library accepts code as supplied;
+with `--file`, the CLI normalizes CRLF and strips only boundary PHP tags.
+
+```sh
+wp-code-snippets get 42 --env-file .env
+wp-code-snippets pull 42 --output backup.php --env-file .env
+wp-code-snippets update 42 --input changes.json --env-file .env --yes
+wp-code-snippets activate 42 --env-file .env --yes
+wp-code-snippets deactivate 42 --env-file .env --yes
+wp-code-snippets delete 42 --env-file .env --yes
+wp-code-snippets restore 42 --env-file .env --yes
+```
+
+`--input` accepts a JSON object; `--input -` reads it from stdin, useful for Python
+consumers. Explicit field arguments override JSON fields. `--output` never overwrites
+an existing file. Without it, `pull` writes raw code to stdout. `push` aliases `update`
+and always requires an ID.
+
+`--dry-run` describes a write without applying it. It is not a signed plan and does
+not detect remote changes. Consumers choose versions and files to publish. The CLI
+does not publish entire directories, resolve ambiguous names or create Git commits.
+
+## Python consumers
+
+Install the npm package in the consuming project. Python can invoke
+`node node_modules/@erseco/code-snippets-client/dist/bin.js` with an argument list,
+parse stdout JSON and check the exit status. Pass configuration through the
+environment and changes through stdin (`--input -`); never interpolate passwords
+or PHP into a shell command. Each invocation keeps one session; separate invocations
+authenticate again.

package/docs/architecture.md

@@ -0,0 +1,41 @@
+# Architecture and compatibility
+
+Initial decision, 2026-09-13. AI assistance: Codex.
+
+One npm package contains the library and CLI. `src/client.ts` adapts the REST API,
+`src/auth.ts` handles authentication, and `src/session.ts` handles transport, cookies
+and redirects. The CLI lives in `src/cli.ts`, with its entry point in `src/bin.ts`.
+
+The client uses Node's native `fetch` and TypeScript compiled with `tsc`, without
+a bundler. `tough-cookie` implements cookie rules and `cheerio/slim` parses HTML
+forms, avoiding custom cookie and attribute parsers. The package is ESM and Node-only.
+It includes no plugin PHP source, institutional configuration or backup data.
+
+Consumers own deployment selection and ordering. There is no generic provider layer,
+server, UI, Git synchronization or telemetry. No application-specific WordPress
+business rules belong in this client.
+
+## Verified contract
+
+The reference is Code Snippets 3.10.2 installed from WordPress.org, specifically
+`php/REST_API/Snippets/Snippets_REST_Controller.php`. The development tree may change
+before release: [upstream controller](https://github.com/codesnippetspro/code-snippets/blob/core-beta/src/php/REST_API/Snippets/Snippets_REST_Controller.php).
+
+- Requests use `?rest_route=/code-snippets/v1/snippets`, supporting plain permalinks.
+- Mutations use POST, accepted by `WP_REST_Server::EDITABLE`.
+- In 3.10.2, activation/deactivation serialize the model as `{}`. A subsequent GET
+  normalizes the result and verifies persisted state.
+- Restoration returns HTTP 204; the client also fetches the snippet afterward.
+- The first deletion trashes the snippet; the next permanently deletes it.
+- HTTP 200 alone is not sufficient evidence of successful activation.
+
+## Test boundaries
+
+Local integration covers WordPress 7.1 / PHP 8.3 / Code Snippets 3.10.2, WordPress
+login, application passwords, permissions and PHP snippet operations. Subsite routing
+and network parameters are tested with HTTP simulations. Initial integration does
+not demonstrate a real multisite network or Pro features.
+
+CAS tests simulate forms and callbacks based on Cassify's flow. They have not run
+against a production Apereo/Cassify deployment, MFA or every possible CAS theme.
+Extend the relevant tests before claiming additional compatibility.

package/docs/authentication.md

@@ -0,0 +1,85 @@
+# Authentication
+
+Set `baseUrl` to the complete site or subsite URL, without query parameters.
+`network: true` selects network snippets. Set `adminUrl` when the administration
+path differs; it must use the same origin as WordPress.
+HTTPS is required unless `allowInsecureHttp: true` explicitly enables local HTTP tests.
+
+## Application passwords
+
+```ts
+const auth = {
+  type: "application-password" as const,
+  username: process.env.WP_USERNAME!,
+  password: process.env.WP_PASSWORD!,
+};
+```
+
+Use a WordPress application password, not the user's regular password. Application
+passwords must be enabled, and the account needs the plugin's permissions.
+[WordPress REST authentication](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/).
+
+## WordPress login
+
+`auth: { type: 'wordpress', username, password }` retrieves the `wp-login.php` form,
+preserves cookies and obtains a nonce from the snippet administration page.
+An optional `loginUrl` supports a custom login path on the same origin.
+It does not run JavaScript or complete MFA, CAPTCHA or interactive SSO challenges.
+
+## CAS / Cassify
+
+```ts
+import { CodeSnippetsClient } from "@erseco/code-snippets-client";
+
+const client = new CodeSnippetsClient({
+  baseUrl: "https://wordpress.example/subsite",
+  auth: {
+    type: "cas",
+    username: process.env.WP_USERNAME!,
+    password: process.env.WP_PASSWORD!,
+    loginUrl: "https://login.example/cas/login",
+  },
+});
+```
+
+By default, the client opens WordPress `wp-login.php` and follows the redirect
+configured by Cassify. It preserves hidden fields, including `execution` and `lt`
+when present, submits `username`, `password` and `_eventId=submit`, then follows the
+service ticket back to WordPress. **WordPress/Cassify validates the ticket**; this
+library is an HTTP form client, not a CAS server or service-ticket validator.
+
+- `entryUrl`: alternate entry point on the WordPress origin.
+- `serviceUrl`: when set, starts directly at `loginUrl?service=...`. Only use a
+  callback accepted by your WordPress setup; some deployments need a PHP session
+  initialized through WordPress first.
+- No images or scripts are executed, and no additional challenges are completed.
+- Forms must use the conventional field names above. Custom field names, MFA,
+  dynamically generated forms and the CAS REST/TGT protocol are not supported.
+- CI simulates login and callback without production credentials. It does not
+  certify universal compatibility with Apereo or Cassify deployments.
+
+Reference flow:
+[WP Cassify](https://github.com/WP-Cassify/wp-cassify-develop/blob/main/wp-cassify/classes/wp_cassify_plugin.php).
+
+## Existing sessions
+
+`auth: { type: 'session', cookie, nonce }` accepts a session obtained externally,
+including after an interactive login. These values are not persisted. The nonce
+must belong to that session and the user must have the required permissions.
+
+## Session boundaries and failures
+
+Cookies remain in memory using `tough-cookie`. Redirects are restricted to the
+configured WordPress and CAS origins. A form cannot submit a password to another
+origin; cross-origin 307/308 redirects cannot replay its body either. Cookies follow
+domain and path rules: different ports do not isolate cookies.
+
+REST requests do not follow redirects to login forms. An expired session fails;
+create a new client to authenticate again. Writes with uncertain outcomes are not
+retried automatically. `timeoutMs` defaults to 30,000. Redirects share their request's
+timeout and are limited to ten hops.
+
+The CLI only loads an explicit `--env-file .env`. Use `WP_AUTH=cas` with
+`CAS_LOGIN_URL`, `WP_USERNAME` and `WP_PASSWORD`. Existing sessions use
+`WP_AUTH=session`, `WP_COOKIE` and `WP_NONCE`. Optional variables are documented in
+`.env.example` and `--help`. Never pass passwords as command-line arguments.

package/docs/development.md

@@ -0,0 +1,49 @@
+# Development and releases
+
+Requirements: Node >=22.14, npm, and Docker for integration tests. `npm run` commands
+also work through an agent on Windows; the Makefile is an optional shortcut.
+
+```sh
+npm ci
+npm run check
+npm run test:package
+npm run test:integration
+```
+
+`check` runs formatting, strict TypeScript, Vitest with coverage and compilation.
+HTTP tests use ephemeral loopback servers. `test:package` creates a tarball, validates
+its file allowlist, installs it in a temporary directory and tests the installed
+import and CLI. Run `npm run build` first when invoking the package test separately.
+CI retains coverage reports as artifacts.
+
+`test:integration` starts `.wp-env.json`, exercises CRUD, metadata, activation,
+double evaluation, permissions, application passwords and single-use snippets. It
+cleans up its snippets and stops the environment in `finally`. It never reads a
+`WP_URL` environment variable. Ports are 8896 and 8897. `npm run wp:destroy` removes
+this disposable environment.
+
+Runtime and development dependencies are pinned with a lockfile. Overrides for
+`qs`, `ws` and `ajv` fix transitive WordPress environment dependencies; remove them
+once upstream resolves patched versions without overrides.
+
+## Releases
+
+1. Update the version and CHANGELOG. Run every check.
+2. Merge into `main` with passing CI.
+3. Create and push a tag named `v` followed by the exact package version.
+4. `publish.yml` repeats CI, installs and verifies the package, publishes that exact
+   tarball to npm and attaches it to a GitHub Release.
+
+There is no per-commit publication or secondary registry: npm and GitHub Releases
+cover installation and artifact downloads. Never reuse a published version number.
+
+The workflow uses npm Trusted Publishing (OIDC). Configure these values in npm:
+
+- Repository: `erseco/code-snippets-client`.
+- Workflow: `publish.yml`.
+- Environment: `npm`.
+
+A new package may require an authenticated first publication before configuring its
+trusted publisher. Never add an npm token to the repository or workflow. A repeated
+publication only succeeds when that version has an identical tarball checksum;
+different contents cause a failure.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@erseco/code-snippets-client",
+  "version": "0.1.0",
+  "description": "TypeScript client and CLI for the WordPress Code Snippets REST API, with WordPress and CAS authentication",
+  "license": "GPL-3.0-only",
+  "author": "Ernesto Serrano",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erseco/code-snippets-client.git"
+  },
+  "homepage": "https://github.com/erseco/code-snippets-client#readme",
+  "bugs": {
+    "url": "https://github.com/erseco/code-snippets-client/issues"
+  },
+  "keywords": [
+    "wordpress",
+    "code-snippets",
+    "rest-api",
+    "cas",
+    "cli",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "wp-code-snippets": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run --coverage",
+    "test:integration": "node scripts/integration.mjs",
+    "check": "npm run format:check && npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build",
+    "test:package": "node scripts/test-package.mjs",
+    "wp:start": "wp-env start",
+    "wp:stop": "wp-env stop",
+    "wp:destroy": "wp-env destroy"
+  },
+  "dependencies": {
+    "cheerio": "1.2.0",
+    "tough-cookie": "6.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.2",
+    "@vitest/coverage-v8": "5.0.0",
+    "@wordpress/env": "11.15.0",
+    "prettier": "3.9.6",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
+  },
+  "overrides": {
+    "qs": "^6.16.0",
+    "ws": "^8.21.3",
+    "ajv": "^8.20.0"
+  }
+}