@epinova/opticli 0.0.0-stage → 0.28.0

package/lib/types.d.ts

@@ -0,0 +1,272 @@
+/** A content reference as opticli takes it: an id ("123"), a version ("123_456"), a GUID or a URL ("/en/about/"). */
+export type ContentRef = string;
+export interface Meta {
+    /** `db` for reads, `agent` for writes, `cli` for local commands; absent on an error. */
+    source?: 'db' | 'agent' | 'cli';
+    /** The opticli version that answered. */
+    version: string;
+    /** Cursor for the next page (`--cursor`). */
+    next?: string;
+    warnings?: string[];
+    /** Present when the database is remote, or has a role other than `local`. */
+    database?: {
+        server: string;
+        name: string;
+        local: boolean;
+        development?: boolean;
+        role?: string;
+    };
+}
+export interface OkEnvelope<T> {
+    ok: true;
+    data: T;
+    meta: Meta;
+}
+/** `error.code`, with the exit code in comments. */
+export type ErrorCode = 'usage' | 'internal' | 'not_found' | 'refused' | 'unreachable' | 'login_failed' | 'timeout' | 'conflict' | 'validation' | 'drift' | 'needs_selection' | 'job_failed' | 'cancelled';
+export interface ErrorBody {
+    code: ErrorCode;
+    message: string;
+    /** What to do next. */
+    hint?: string;
+    details?: Record<string, unknown>;
+}
+export interface ErrorEnvelope {
+    ok: false;
+    error: ErrorBody;
+    /** opticli 0.27.0 and newer: the version that failed. */
+    meta?: Pick<Meta, 'version'>;
+}
+export type Envelope<T> = OkEnvelope<T> | ErrorEnvelope;
+/**
+ * A property value as `--values` takes it: a string (also HTML for rich text, an id for a reference), number, boolean
+ * or null (clears it), or a structured value (a ContentArea, a link, a local block, a list).
+ */
+export type PropertyValue = string | number | boolean | null | readonly ContentAreaItem[] | LinkValue | readonly PropertyValue[] | {
+    readonly [property: string]: PropertyValue;
+};
+/** A ContentArea item: existing content by ref or GUID, or an inline block (CMS 12.20+). */
+export type ContentAreaItem = {
+    readonly ref: ContentRef;
+    readonly displayOption?: string;
+    readonly group?: string;
+    readonly visitorGroups?: readonly string[];
+} | {
+    readonly guid: string;
+    readonly displayOption?: string;
+} | {
+    readonly type: string;
+    readonly name?: string;
+    readonly properties: Properties;
+    readonly displayOption?: string;
+};
+export interface LinkValue {
+    readonly href: ContentRef;
+    readonly text?: string;
+    readonly title?: string;
+    readonly target?: string;
+}
+export type Properties = {
+    readonly [property: string]: PropertyValue;
+};
+export interface ServeResult {
+    state: 'running' | 'stopped' | 'starting' | (string & {});
+    message: string;
+    mode?: 'background' | 'foreground' | 'ide';
+    pid?: number;
+    port?: number;
+    /** Where the site agent listens (HTTP on 127.0.0.1). */
+    url?: string;
+    /** With `--https`: the address to browse. */
+    browseUrl?: string;
+    scheduler?: 'on' | 'off';
+    /** The site agent the running site has: its opticli version, CMS version and runtime. */
+    agent?: {
+        version: string;
+        protocol: number;
+        cmsVersion: string;
+        runtime: string;
+        environment: string;
+    };
+    /** `serve --stop`: whether a site was stopped. */
+    stopped?: boolean;
+}
+export interface ChangedProperty {
+    property: string;
+    before?: unknown;
+    after?: unknown;
+}
+/** What `create`, `set`, `publish` and the other single writes return. */
+export interface WriteResult {
+    ref: ContentRef;
+    /** The version written (`id_version`); for a dry run, the version the change was applied to. */
+    version?: string;
+    guid?: string;
+    type?: string;
+    name?: string;
+    language?: string;
+    status?: 'published' | 'checkedOut' | 'checkedIn' | 'delayedPublish' | 'awaitingApproval' | (string & {});
+    parent?: ContentRef;
+    saved: boolean;
+    published: boolean;
+    dryRun: boolean;
+    valid: boolean;
+    baseVersion?: string;
+    changes?: ChangedProperty[];
+    validation?: {
+        property?: string;
+        message: string;
+        severity?: string;
+    }[];
+    /** The version that was live before a publish: publish it again to go back. */
+    previouslyPublished?: string;
+    /**
+     * The public URL, host-relative on the served site as `get` shows it; for a draft of content never published, where
+     * it will be. None for blocks, folders and a dry-run create.
+     */
+    url?: string;
+}
+export interface DeleteResult {
+    ref: ContentRef;
+    guid: string;
+    name: string;
+    parent: ContentRef;
+    previousParent: ContentRef;
+    moved: boolean;
+    dryRun: boolean;
+    descendants: number;
+    recycleBin: boolean;
+}
+export interface UrlResult {
+    ref: ContentRef;
+    guid: string;
+    type: string;
+    languages: {
+        language: string;
+        name: string;
+        status: string;
+        path: string | null;
+        url: string | null;
+        site: string;
+    }[];
+}
+export interface PropertyOut {
+    type: string;
+    value: unknown;
+    culture?: string;
+    truncated?: boolean;
+    length?: number;
+}
+/** What `get` returns. */
+export interface ContentItem {
+    ref: ContentRef;
+    guid: string;
+    type: string;
+    name: string;
+    language: string;
+    status: string;
+    url?: string;
+    kind: 'page' | 'block' | 'media' | 'folder' | (string & {});
+    version: string;
+    parent: ContentRef;
+    saved: string;
+    changedBy: string;
+    properties: Record<string, PropertyOut>;
+}
+interface StepBase {
+    /** Names what this step makes, for "$id" in later steps (needed with a plan's `guidNamespace`). */
+    readonly id?: string;
+    readonly guid?: string;
+    readonly publish?: boolean;
+    readonly lang?: string;
+}
+export type PlanStep = (StepBase & {
+    readonly op: 'create';
+    readonly parent?: ContentRef;
+    readonly for?: ContentRef;
+    readonly type: string;
+    readonly name: string;
+    readonly properties?: Properties;
+}) | (StepBase & {
+    readonly op: 'block';
+    readonly type: string;
+    readonly name: string;
+    readonly for?: ContentRef;
+    readonly parent?: ContentRef;
+    readonly properties?: Properties;
+}) | (StepBase & {
+    readonly op: 'upload';
+    readonly file: string;
+    readonly for?: ContentRef;
+    readonly parent?: ContentRef;
+    readonly name?: string;
+    readonly properties?: Properties;
+}) | (StepBase & {
+    readonly op: 'set';
+    readonly ref: ContentRef;
+    readonly properties?: Properties;
+    readonly name?: string;
+    readonly from?: string;
+}) | (StepBase & {
+    readonly op: 'area';
+    readonly ref: ContentRef;
+    readonly property: string;
+    readonly action: 'add' | 'remove' | 'move' | 'set';
+    readonly item?: ContentRef;
+    readonly type?: string;
+    readonly values?: Properties;
+    readonly at?: number;
+    readonly displayOption?: string;
+}) | (StepBase & {
+    readonly op: 'publish' | 'unpublish' | 'discard';
+    readonly ref: ContentRef;
+    readonly version?: string;
+}) | (StepBase & {
+    readonly op: 'move';
+    readonly ref: ContentRef;
+    readonly to: ContentRef;
+}) | (StepBase & {
+    readonly op: 'delete';
+    readonly ref: ContentRef;
+    readonly ignoreReferences?: boolean;
+}) | (StepBase & {
+    readonly op: 'restore';
+    readonly ref: ContentRef;
+    readonly to?: ContentRef;
+}) | (StepBase & {
+    readonly op: 'translate';
+    readonly ref: ContentRef;
+    readonly lang: string;
+    readonly name?: string;
+    readonly properties?: Properties;
+});
+export interface Plan {
+    /** Gives every create, block and upload a GUID derived from its `id`, so the plan can run again. */
+    readonly guidNamespace?: string;
+    readonly operations: readonly PlanStep[];
+}
+/** The `id`s a plan's steps declare, as a union of string literals for a plan written `as const`. */
+export type PlanIds<P extends Plan> = P['operations'][number] extends infer S ? (S extends {
+    readonly id: infer I extends string;
+} ? I : never) : never;
+export interface PlanStepResult {
+    index: number;
+    op: PlanStep['op'] | (string & {});
+    id?: string;
+    guid?: string;
+    status: 'saved' | 'unchanged' | 'valid' | 'simulated' | 'deferred' | 'invalid' | 'failed' | (string & {});
+    result?: Partial<WriteResult> & {
+        existing?: boolean;
+        restored?: boolean;
+    };
+    error?: ErrorBody;
+    warnings?: string[];
+    undo?: unknown;
+}
+export interface ApplyResult {
+    dryRun: boolean;
+    operations: PlanStepResult[];
+    /** `id` of each create, block and upload → the content it made or updated. */
+    created: Record<string, ContentRef>;
+}
+export {};

package/lib/types.js

@@ -0,0 +1,4 @@
+// Types for opticli's JSON output: the README's "Output and exit codes" and skill/reference.md.
+// Hand-written for the commands a test suite needs; result types list the fields worth reading, and opticli may add
+// more. Input types are readonly, so plans and values written `as const` fit.
+export {};

package/lib/version.d.ts

@@ -0,0 +1,4 @@
+/** This package's version, which build.mjs sets: opticli's version. */
+export declare const version = "0.0.0-dev";
+/** The oldest opticli this package works with: the one released with it. */
+export declare const requiredOpticli: string;

package/lib/version.js

@@ -0,0 +1,4 @@
+/** This package's version, which build.mjs sets: opticli's version. */
+export const version = '0.28.0';
+/** The oldest opticli this package works with: the one released with it. */
+export const requiredOpticli = version.split('-')[0];

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@epinova/opticli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.28.0",
+  "description": "Typed Node API and Playwright fixtures for opticli: start an Optimizely CMS site, seed test content and clean up after the tests",
+  "license": "MPL-2.0",
+  "type": "module",
+  "keywords": [
+    "optimizely",
+    "episerver",
+    "cms",
+    "playwright",
+    "testing",
+    "opticli"
+  ],
+  "homepage": "https://github.com/epinova/opticli/tree/main/npm#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/epinova/opticli.git",
+    "directory": "npm"
+  },
+  "bugs": "https://github.com/epinova/opticli/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./playwright": {
+      "types": "./lib/playwright/index.d.ts",
+      "default": "./lib/playwright/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ]
+}