@digital-gravy/etch-public-api 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -12,7 +12,7 @@ interface EtchBlockContext {
      * panel. This is editor UI state, not document data — most scripts can
      * ignore it.
      */
-    structureState?: "open" | "closed";
+    structureState?: 'open' | 'closed';
     /** Whether the block is hidden (not rendered) on the canvas. */
     hidden?: boolean;
 }
@@ -64,7 +64,7 @@ interface EtchBlockCommon {
 }
 /** A text block (`etch/text`). */
 interface EtchTextBlockJson extends EtchBlockCommon {
-    type: "etch/text";
+    type: 'etch/text';
     /** The block's text content. */
     text: string;
 }
@@ -76,7 +76,7 @@ interface EtchTextBlockJson extends EtchBlockCommon {
  * `blocks.create()` / `blocks.replace()` ignore them.
  */
 interface EtchElementBlockJson extends EtchBlockCommon {
-    type: "etch/element";
+    type: 'etch/element';
     /** The HTML tag name, e.g. `div`, `p`, `h1`. */
     tag: string;
     /** HTML attributes. */
@@ -90,7 +90,7 @@ interface EtchElementBlockJson extends EtchBlockCommon {
  * {@link EtchElementBlockJson}).
  */
 interface EtchDynamicElementBlockJson extends EtchBlockCommon {
-    type: "etch/dynamic-element";
+    type: 'etch/dynamic-element';
     /** HTML attributes (the rendered tag is read from `attributes.tag`). */
     attributes: EtchHtmlAttributes;
 }
@@ -111,7 +111,7 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
-    type: "etch/dynamic-image";
+    type: 'etch/dynamic-image';
     /** HTML attributes (e.g. `src`, `alt`). */
     attributes: EtchHtmlAttributes;
 }
@@ -129,13 +129,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
-    type: "etch/svg";
+    type: 'etch/svg';
     /** HTML/SVG attributes. */
     attributes: EtchHtmlAttributes;
 }
 /** A loop block (`etch/loop`) that repeats its children over a data source. */
 interface EtchLoopBlockJson extends EtchBlockCommon {
-    type: "etch/loop";
+    type: 'etch/loop';
     /** Variable name bound to the current item (e.g. `item`). */
     itemId: string;
     /** What the block iterates over (a dynamic path); omitted when bound via `loopId`. */
@@ -149,13 +149,13 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
 }
 /** A conditional block (`etch/condition`); renders its children when the expression holds. */
 interface EtchConditionBlockJson extends EtchBlockCommon {
-    type: "etch/condition";
+    type: 'etch/condition';
     /** The condition expression. */
     conditionString: string;
 }
 /** An instance of a reusable component (`etch/component`). */
 interface EtchComponentBlockJson extends EtchBlockCommon {
-    type: "etch/component";
+    type: 'etch/component';
     /** Id of the component being instantiated. */
     componentId: number;
     /** Values bound to the component's properties. */
@@ -163,23 +163,23 @@ interface EtchComponentBlockJson extends EtchBlockCommon {
 }
 /** Content projected into a component slot (`etch/slot-content`). */
 interface EtchSlotContentBlockJson extends EtchBlockCommon {
-    type: "etch/slot-content";
+    type: 'etch/slot-content';
     /** Name of the slot this content targets. */
     slotName: string;
 }
 /** A slot placeholder inside a component definition (`etch/slot-placeholder`). */
 interface EtchSlotPlaceholderBlockJson extends EtchBlockCommon {
-    type: "etch/slot-placeholder";
+    type: 'etch/slot-placeholder';
     /** Name of the slot. */
     slotName: string;
 }
 /** The post-content insertion point (`etch/post-content`). No extra fields. */
 interface EtchPostContentBlockJson extends EtchBlockCommon {
-    type: "etch/post-content";
+    type: 'etch/post-content';
 }
 /** A raw-HTML block (`etch/raw-html`). */
 interface EtchRawHtmlBlockJson extends EtchBlockCommon {
-    type: "etch/raw-html";
+    type: 'etch/raw-html';
     /** Sanitized HTML content. */
     content: string;
     /** The original, unsanitized HTML as authored. */
@@ -187,7 +187,7 @@ interface EtchRawHtmlBlockJson extends EtchBlockCommon {
 }
 /** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
 interface EtchPassthroughBlockJson extends EtchBlockCommon {
-    type: "etch/passthrough";
+    type: 'etch/passthrough';
     /** The wrapped Gutenberg block. */
     gutenbergBlock: GutenbergBlock;
 }
@@ -201,7 +201,7 @@ interface EtchPassthroughBlockJson extends EtchBlockCommon {
  */
 type EtchBlockJson = EtchTextBlockJson | EtchElementBlockJson | EtchDynamicElementBlockJson | EtchDynamicImageBlockJson | EtchSvgBlockJson | EtchLoopBlockJson | EtchConditionBlockJson | EtchComponentBlockJson | EtchSlotContentBlockJson | EtchSlotPlaceholderBlockJson | EtchPostContentBlockJson | EtchRawHtmlBlockJson | EtchPassthroughBlockJson;
 /** Every known block `type` string (the discriminants of {@link EtchBlockJson}). */
-type EtchBlockTypeName = EtchBlockJson["type"];
+type EtchBlockTypeName = EtchBlockJson['type'];
 /** Read-only identity attached to every serialized (read) block. */
 interface BlockIdentity {
     /** Stable id of this block. */
@@ -217,7 +217,7 @@ interface BlockIdentity {
  * writable {@link EtchBlockJson}, so they cannot be set via
  * `blocks.create()` / `blocks.replace()`.
  */
-type StyledBlockType = "etch/element" | "etch/dynamic-element" | "etch/dynamic-image" | "etch/svg";
+type StyledBlockType = 'etch/element' | 'etch/dynamic-element' | 'etch/dynamic-image' | 'etch/svg';
 /** The read-only `styles` exposed on a {@link StyledBlockType} when reading. */
 interface ReadOnlyBlockStyles {
     /** Ids of the global styles applied to this block (read-only). */
@@ -227,7 +227,7 @@ interface ReadOnlyBlockStyles {
  * Attach read-only identity (`id`/`parentId`) to a block, recursively, plus the
  * read-only `styles` array for the {@link StyledBlockType}s that carry one.
  */
-type WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, "children"> & BlockIdentity & (B extends {
+type WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, 'children'> & BlockIdentity & (B extends {
     type: StyledBlockType;
 } ? ReadOnlyBlockStyles : unknown) : never;
 /**
@@ -256,8 +256,10 @@ interface BlockPatch {
     /** Hide or show the block on the canvas. */
     hidden?: boolean;
     /**
-     * Merge HTML attributes — a key set to `undefined` removes that attribute.
-     * Only valid on HTML blocks.
+     * Merge attributes — a key set to `undefined` removes that attribute. Valid
+     * on HTML blocks (free-form HTML attributes) and on component instances,
+     * whose attributes are their bound props — a closed schema, so each key must
+     * be a property declared by the component (an unknown key is rejected).
      */
     attributes?: Record<string, string | undefined>;
     /** Replace the text content. Only valid on text blocks. */
@@ -299,11 +301,26 @@ interface EtchBlocksApi {
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
     rename(blockId: string, name: string): void;
-    /** Read an HTML attribute, or `undefined` when it is not set. */
+    /**
+     * Read an attribute, or `undefined` when it is not set. Works on HTML blocks
+     * (HTML attributes) and component instances (bound prop values). Throws
+     * `WRONG_BLOCK_TYPE` for a block that has no attributes (e.g. a text block).
+     */
     getAttribute(blockId: string, key: string): string | undefined;
-    /** Set an HTML attribute; omit `value` for a valueless (boolean) attribute. */
+    /**
+     * Set an attribute; omit `value` for a valueless (boolean) attribute. Works
+     * on HTML blocks and component instances. On a component, `key` must be a
+     * declared property — props are a closed schema — otherwise
+     * `INVALID_ARGUMENT` is thrown (or `OPERATION_FAILED` if the component
+     * definition has not loaded yet). Throws `WRONG_BLOCK_TYPE` for a block with
+     * no attributes.
+     */
     setAttribute(blockId: string, key: string, value?: string): void;
-    /** Remove an HTML attribute. */
+    /**
+     * Remove an attribute. Works on HTML blocks and component instances. On a
+     * component, `key` must be a declared property (see {@link setAttribute}).
+     * Throws `WRONG_BLOCK_TYPE` for a block with no attributes.
+     */
     removeAttribute(blockId: string, key: string): void;
     /** Add a CSS class to the block. */
     addClass(blockId: string, className: string): void;
@@ -373,9 +390,9 @@ interface MetaQueryItem {
     /** The value(s) to compare against. */
     value: string | number | Array<string | number>;
     /** Comparison operator (defaults to `=`). */
-    compare?: "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN" | "EXISTS" | "NOT EXISTS";
+    compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
     /** SQL type the value is cast to before comparison. */
-    type?: "NUMERIC" | "BINARY" | "CHAR" | "DATE" | "DATETIME" | "DECIMAL" | "SIGNED" | "TIME" | "UNSIGNED";
+    type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
     [key: string]: unknown;
 }
 /**
@@ -386,11 +403,11 @@ interface TaxQueryItem {
     /** The taxonomy to query (e.g. `category`, `post_tag`). */
     taxonomy: string;
     /** Which term field `terms` refers to. */
-    field: "term_id" | "slug" | "name";
+    field: 'term_id' | 'slug' | 'name';
     /** The term(s) to match. */
     terms: string | number | Array<string | number>;
     /** How to match the terms (defaults to `IN`). */
-    operator?: "IN" | "NOT IN" | "AND";
+    operator?: 'IN' | 'NOT IN' | 'AND';
     /** Whether to include child terms of a hierarchical taxonomy. */
     include_children?: boolean;
     [key: string]: unknown;
@@ -412,11 +429,11 @@ interface WpQueryArgs {
     /** Alias of `paged` used in some contexts. */
     page?: NumericParam;
     /** Field to order results by. */
-    orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
+    orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     /** Post status to include. */
-    post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
+    post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
     /** Whether to ignore sticky posts. */
     ignore_sticky_posts?: BooleanParam;
     /** Author id (number) or username (string). */
@@ -442,9 +459,9 @@ interface WpTermsArgs {
     /** Taxonomy to fetch terms from. */
     taxonomy?: string;
     /** Field to order terms by. */
-    orderby?: "name" | "slug" | "term_group" | "term_id" | "description" | "count" | (string & {});
+    orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     [key: string]: unknown;
 }
 /** WordPress user query arguments (extensible). */
@@ -460,9 +477,9 @@ interface WpUsersArgs {
     /** Columns the `search` keyword is matched against. */
     search_columns?: string[] | string;
     /** Field to order users by. */
-    orderby?: "ID" | "display_name" | "name" | "user_login" | "user_email" | "user_registered" | "post_count" | "meta_value" | "meta_value_num" | (string & {});
+    orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     /** Number of users to return. */
     number?: NumericParam;
     /** Number of users to skip. */
@@ -473,19 +490,19 @@ interface WpUsersArgs {
 }
 /** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
 type EtchLoopConfig = {
-    type: "wp-query";
+    type: 'wp-query';
     args: WpQueryArgs;
 } | {
-    type: "wp-terms";
+    type: 'wp-terms';
     args: WpTermsArgs;
 } | {
-    type: "wp-users";
+    type: 'wp-users';
     args: WpUsersArgs;
 } | {
-    type: "main-query";
+    type: 'main-query';
     args: WpQueryArgs;
 } | {
-    type: "json";
+    type: 'json';
     data: unknown[];
 };
 /** A loop definition (extensible). */
@@ -549,7 +566,7 @@ interface EtchLoopsApi {
  * - `attribute` — `[data-foo]`, `[type="submit"]`, etc.
  * - `custom` — anything else (pseudo-classes, combinators, etc.)
  */
-type StyleSelectorType = "class" | "id" | "tag" | "element" | "attribute" | "custom";
+type StyleSelectorType = 'class' | 'id' | 'tag' | 'element' | 'attribute' | 'custom';
 /** A style entry as returned by `styles.list()`. */
 interface StyleSummary {
     /** Stable id of the style rule. */
@@ -636,7 +653,7 @@ interface EtchStylesApi {
  * Global stylesheet shapes and the `etch.stylesheets` API surface.
  */
 /** Type of a global stylesheet. */
-type StylesheetType = "default" | "@custom-media";
+type StylesheetType = 'default' | '@custom-media';
 /** A global stylesheet entry. */
 interface StylesheetSummary {
     /** Stable id of the stylesheet. */
@@ -737,8 +754,8 @@ type SelectOptionsString = string;
  */
 interface StringComponentProperty {
     type: {
-        primitive: "string";
-        specialized?: "color" | "url" | "image" | "select" | "array" | "wpMediaId";
+        primitive: 'string';
+        specialized?: 'color' | 'url' | 'image' | 'select' | 'array' | 'wpMediaId';
     };
     /** Default value. */
     default?: string;
@@ -760,7 +777,7 @@ interface StringComponentProperty {
  */
 interface NumberComponentProperty {
     type: {
-        primitive: "number";
+        primitive: 'number';
     };
     /** Default value. */
     default?: number;
@@ -770,7 +787,7 @@ interface NumberComponentProperty {
 /** A boolean property. */
 interface BooleanComponentProperty {
     type: {
-        primitive: "boolean";
+        primitive: 'boolean';
     };
     /** Default value (a string is allowed for expression-driven defaults). */
     default?: boolean | string;
@@ -784,7 +801,7 @@ interface BooleanComponentProperty {
  */
 interface ObjectComponentProperty {
     type: {
-        primitive: "object";
+        primitive: 'object';
         specialized?: string;
     };
     /** Default value. */
@@ -799,7 +816,7 @@ interface ObjectComponentProperty {
  */
 interface ArrayComponentProperty {
     type: {
-        primitive: "array";
+        primitive: 'array';
         specialized?: string;
     };
     /** Default value. */
@@ -808,8 +825,8 @@ interface ArrayComponentProperty {
 /** A list of CSS class names — an `array` specialized as `'class'`. */
 interface ClassComponentProperty {
     type: {
-        primitive: "array";
-        specialized: "class";
+        primitive: 'array';
+        specialized: 'class';
     };
     /** Default value. */
     default?: string[];
@@ -817,8 +834,8 @@ interface ClassComponentProperty {
 /** A group of nested properties — an `object` specialized as `'group'` (no default). */
 interface GroupComponentProperty {
     type: {
-        primitive: "object";
-        specialized: "group";
+        primitive: 'object';
+        specialized: 'group';
     };
     /** The nested properties in this group. */
     properties: ComponentProperty[];
@@ -826,8 +843,8 @@ interface GroupComponentProperty {
 /** A repeatable group — an `array` specialized as `'repeater'` (no default). */
 interface RepeaterComponentProperty {
     type: {
-        primitive: "array";
-        specialized: "repeater";
+        primitive: 'array';
+        specialized: 'repeater';
     };
     /** The nested properties repeated per row. */
     properties: ComponentProperty[];
@@ -835,8 +852,8 @@ interface RepeaterComponentProperty {
 /** A conditional group gated by an expression — a `string` specialized as `'condition'`. */
 interface ConditionComponentProperty {
     type: {
-        primitive: "string";
-        specialized: "condition";
+        primitive: 'string';
+        specialized: 'condition';
     };
     /** The nested properties shown when the condition holds. */
     properties: ComponentProperty[];
@@ -942,7 +959,7 @@ interface EtchComponentsApi {
  * - `style-manager` — the global style manager
  * - `loop-manager` — the loop manager
  */
-type NavigationPlace = "builder" | "templates" | "style-manager" | "content-hub" | "loop-manager";
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -991,7 +1008,7 @@ interface EtchNavigationApi {
  * Custom field group/value shapes and the `etch.fields` API surface.
  */
 /** Custom field type. Open-ended for future field types. */
-type CustomFieldType = "text" | "textarea" | "number" | "boolean" | (string & {});
+type CustomFieldType = 'text' | 'textarea' | 'number' | 'boolean' | (string & {});
 /** A custom field definition (extensible). */
 interface CustomField {
     /** Display label. */
@@ -1009,13 +1026,13 @@ interface CustomField {
 /** Where a custom field group is assigned. */
 type CustomFieldAssignment = {
     post_types: string[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 } | {
     post_ids: number[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 } | {
     taxonomies: string[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 };
 /** A custom field group definition (extensible). */
 interface CustomFieldGroup {
@@ -1111,7 +1128,7 @@ interface EtchFieldsApi {
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
 /** Canvas color scheme. */
-type ColorScheme = "light" | "dark";
+type ColorScheme = 'light' | 'dark';
 /** Builder app/chrome controls: color scheme, interface visibility, exit. */
 interface EtchUiApi {
     /** The current canvas color scheme. */

package/dist/index.js

@@ -45,7 +45,10 @@ function getEtch(options = {}) {
     return etch.connect(options);
   }
   if (options.apiVersion) {
-    warnIfIncompatible(options.apiVersion, etch.apiVersion ?? ETCH_API_VERSION);
+    warnIfIncompatible(
+      options.apiVersion,
+      etch.apiVersion ?? ETCH_API_VERSION
+    );
   }
   return etch;
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/version.ts","../src/client.ts"],"names":[],"mappings":";AAyBO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAGvC,WAAA,CAAY,MAAwB,OAAA,EAAiB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACb;AACD;AAGO,SAAS,eAAe,KAAA,EAAuC;AACrE,EAAA,OAAO,KAAA,YAAiB,YAAA,IAAiB,KAAA,EAAiB,IAAA,KAAS,cAAA;AACpE;;;AC9BO,IAAM,gBAAA,GAAmB;;;ACIhC,SAAS,QAAA,GAA6B;AACrC,EAAA,MAAM,KAAA,GAAQ,UAAA;AACd,EAAA,OAAO,KAAA,CAAM,IAAA;AACd;AAMO,SAAS,eAAA,GAA2B;AAC1C,EAAA,OAAO,UAAS,KAAM,MAAA;AACvB;AAGA,SAAS,QAAQ,OAAA,EAAgC;AAChD,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,OAAO,CAAA;AACtC,EAAA,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,IAAA;AACnC;AAOA,SAAS,kBAAA,CAAmB,WAAmB,OAAA,EAAuB;AACrE,EAAA,MAAM,IAAA,GAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,QAAQ,OAAO,CAAA;AAC5B,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,IAAA,EAAM;AAErD,EAAA,OAAA,CAAQ,IAAA;AAAA,IACP,CAAA,qDAAA,EAAwD,SAAS,CAAA,wBAAA,EAC9C,OAAO,CAAA,sBAAA;AAAA,GAC3B;AACD;AAsBO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EAAS;AAC3D,EAAA,MAAM,OAAO,QAAA,EAAS;AACtB,EAAA,IAAI,CAAC,IAAA,EAAM;AACV,IAAA,MAAM,IAAI,YAAA;AAAA,MACT,eAAA;AAAA,MACA;AAAA,KAED;AAAA,EACD;AAEA,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,IAAI,QAAQ,UAAA,EAAY;AACvB,IAAA,kBAAA,CAAmB,OAAA,CAAQ,UAAA,EAAY,IAAA,CAAK,UAAA,IAAc,gBAAgB,CAAA;AAAA,EAC3E;AACA,EAAA,OAAO,IAAA;AACR","file":"index.js","sourcesContent":["/**\n * Error codes thrown by the public `window.etch` API.\n *\n * The API throws typed errors (rather than returning sentinels) so that AI\n * assistants and plugin authors can `try`/`catch` and react to a precise cause.\n *\n * The union ends with `(string & {})` so that codes added by newer Etch\n * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for\n * the known values.\n */\nexport type EtchApiErrorCode =\n\t| 'BLOCK_NOT_FOUND'\n\t| 'WRONG_BLOCK_TYPE'\n\t| 'READONLY'\n\t| 'INVALID_ARGUMENT'\n\t| 'LOOP_NOT_FOUND'\n\t| 'STYLE_NOT_FOUND'\n\t| 'STYLESHEET_NOT_FOUND'\n\t| 'COMPONENT_NOT_FOUND'\n\t| 'POST_NOT_FOUND'\n\t| 'OPERATION_FAILED'\n\t| 'NOT_AVAILABLE'\n\t| (string & {});\n\n/** Error thrown by the public Etch API (and by this client). */\nexport class EtchApiError extends Error {\n\treadonly code: EtchApiErrorCode;\n\n\tconstructor(code: EtchApiErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'EtchApiError';\n\t\tthis.code = code;\n\t}\n}\n\n/** Narrow an unknown caught value to an {@link EtchApiError}. */\nexport function isEtchApiError(value: unknown): value is EtchApiError {\n\treturn value instanceof EtchApiError || (value as Error)?.name === 'EtchApiError';\n}\n","/**\n * Version of the Etch scripting **contract** this package targets, independent\n * of the Etch product version and of this package's own npm version.\n *\n * `0.x` signals the surface is **experimental** and may change without a major\n * bump until it stabilizes. It matches the value returned by the runtime's\n * {@link Etch.apiVersion} getter on `window.etch`.\n */\nexport const ETCH_API_VERSION = '0.x';\n","import type { ConnectOptions, Etch } from './contract';\nimport { EtchApiError } from './errors';\nimport { ETCH_API_VERSION } from './version';\n\ndeclare global {\n\tinterface Window {\n\t\t/** The Etch scripting API, present once the builder has loaded. */\n\t\tetch?: Etch;\n\t}\n}\n\n/** Read `window.etch` from whatever global object exists, or `undefined`. */\nfunction readEtch(): Etch | undefined {\n\tconst scope = globalThis as { etch?: Etch };\n\treturn scope.etch;\n}\n\n/**\n * Whether the Etch scripting API is present on the page. Use this to guard code\n * that should no-op when not running inside the builder.\n */\nexport function isEtchAvailable(): boolean {\n\treturn readEtch() !== undefined;\n}\n\n/** The major version number of a semver-ish string, or `null` if unparseable. */\nfunction majorOf(version: string): number | null {\n\tconst match = /^\\D*(\\d+)/.exec(version);\n\treturn match ? Number(match[1]) : null;\n}\n\n/**\n * Best-effort compatibility check for `0.x` runtimes that have no native\n * `connect()`. Warns (does not throw) when the requested major differs from the\n * runtime's, so experimental consumers aren't hard-blocked.\n */\nfunction warnIfIncompatible(requested: string, runtime: string): void {\n\tconst want = majorOf(requested);\n\tconst have = majorOf(runtime);\n\tif (want === null || have === null || want === have) return;\n\t// eslint-disable-next-line no-console\n\tconsole.warn(\n\t\t`[@digital-gravy/etch-public-api] Requested Etch API v${requested} but the ` +\n\t\t\t`page provides v${runtime}. Behavior may differ.`\n\t);\n}\n\n/**\n * Acquire the Etch scripting API from the page.\n *\n * The runtime lives on `window.etch` (injected by the builder); this returns it\n * typed. When the page exposes a future stable runtime with a native\n * `connect()`, version negotiation is delegated to it. On today's `0.x`\n * runtime, the global is returned directly after a best-effort version check.\n *\n * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.\n *\n * @example\n * ```ts\n * import { getEtch } from '@etchwp/public-api';\n *\n * const etch = getEtch();\n * const ids = etch.blocks.find({ type: 'text' });\n * etch.blocks.setText(ids[0], 'Hello');\n * await etch.saveAsync();\n * ```\n */\nexport function getEtch(options: ConnectOptions = {}): Etch {\n\tconst etch = readEtch();\n\tif (!etch) {\n\t\tthrow new EtchApiError(\n\t\t\t'NOT_AVAILABLE',\n\t\t\t'window.etch is not available. The Etch builder is not loaded on this page, ' +\n\t\t\t\t'or getEtch() ran before it finished initializing.'\n\t\t);\n\t}\n\n\tif (typeof etch.connect === 'function') {\n\t\treturn etch.connect(options);\n\t}\n\n\tif (options.apiVersion) {\n\t\twarnIfIncompatible(options.apiVersion, etch.apiVersion ?? ETCH_API_VERSION);\n\t}\n\treturn etch;\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/version.ts","../src/client.ts"],"names":[],"mappings":";AAyBO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAGvC,WAAA,CAAY,MAAwB,OAAA,EAAiB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACb;AACD;AAGO,SAAS,eAAe,KAAA,EAAuC;AACrE,EAAA,OACC,KAAA,YAAiB,YAAA,IAChB,KAAA,EAAiB,IAAA,KAAS,cAAA;AAE7B;;;ACjCO,IAAM,gBAAA,GAAmB;;;ACIhC,SAAS,QAAA,GAA6B;AACrC,EAAA,MAAM,KAAA,GAAQ,UAAA;AACd,EAAA,OAAO,KAAA,CAAM,IAAA;AACd;AAMO,SAAS,eAAA,GAA2B;AAC1C,EAAA,OAAO,UAAS,KAAM,MAAA;AACvB;AAGA,SAAS,QAAQ,OAAA,EAAgC;AAChD,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,OAAO,CAAA;AACtC,EAAA,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,IAAA;AACnC;AAOA,SAAS,kBAAA,CAAmB,WAAmB,OAAA,EAAuB;AACrE,EAAA,MAAM,IAAA,GAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,QAAQ,OAAO,CAAA;AAC5B,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,IAAA,EAAM;AACrD,EAAA,OAAA,CAAQ,IAAA;AAAA,IACP,CAAA,qDAAA,EAAwD,SAAS,CAAA,wBAAA,EAC9C,OAAO,CAAA,sBAAA;AAAA,GAC3B;AACD;AAsBO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EAAS;AAC3D,EAAA,MAAM,OAAO,QAAA,EAAS;AACtB,EAAA,IAAI,CAAC,IAAA,EAAM;AACV,IAAA,MAAM,IAAI,YAAA;AAAA,MACT,eAAA;AAAA,MACA;AAAA,KAED;AAAA,EACD;AAEA,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,IAAI,QAAQ,UAAA,EAAY;AACvB,IAAA,kBAAA;AAAA,MACC,OAAA,CAAQ,UAAA;AAAA,MACR,KAAK,UAAA,IAAc;AAAA,KACpB;AAAA,EACD;AACA,EAAA,OAAO,IAAA;AACR","file":"index.js","sourcesContent":["/**\n * Error codes thrown by the public `window.etch` API.\n *\n * The API throws typed errors (rather than returning sentinels) so that AI\n * assistants and plugin authors can `try`/`catch` and react to a precise cause.\n *\n * The union ends with `(string & {})` so that codes added by newer Etch\n * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for\n * the known values.\n */\nexport type EtchApiErrorCode =\n\t| 'BLOCK_NOT_FOUND'\n\t| 'WRONG_BLOCK_TYPE'\n\t| 'READONLY'\n\t| 'INVALID_ARGUMENT'\n\t| 'LOOP_NOT_FOUND'\n\t| 'STYLE_NOT_FOUND'\n\t| 'STYLESHEET_NOT_FOUND'\n\t| 'COMPONENT_NOT_FOUND'\n\t| 'POST_NOT_FOUND'\n\t| 'OPERATION_FAILED'\n\t| 'NOT_AVAILABLE'\n\t| (string & {});\n\n/** Error thrown by the public Etch API (and by this client). */\nexport class EtchApiError extends Error {\n\treadonly code: EtchApiErrorCode;\n\n\tconstructor(code: EtchApiErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'EtchApiError';\n\t\tthis.code = code;\n\t}\n}\n\n/** Narrow an unknown caught value to an {@link EtchApiError}. */\nexport function isEtchApiError(value: unknown): value is EtchApiError {\n\treturn (\n\t\tvalue instanceof EtchApiError ||\n\t\t(value as Error)?.name === 'EtchApiError'\n\t);\n}\n","/**\n * Version of the Etch scripting **contract** this package targets, independent\n * of the Etch product version and of this package's own npm version.\n *\n * `0.x` signals the surface is **experimental** and may change without a major\n * bump until it stabilizes. It matches the value returned by the runtime's\n * {@link Etch.apiVersion} getter on `window.etch`.\n */\nexport const ETCH_API_VERSION = '0.x';\n","import type { ConnectOptions, Etch } from './contract';\nimport { EtchApiError } from './errors';\nimport { ETCH_API_VERSION } from './version';\n\ndeclare global {\n\tinterface Window {\n\t\t/** The Etch scripting API, present once the builder has loaded. */\n\t\tetch?: Etch;\n\t}\n}\n\n/** Read `window.etch` from whatever global object exists, or `undefined`. */\nfunction readEtch(): Etch | undefined {\n\tconst scope = globalThis as { etch?: Etch };\n\treturn scope.etch;\n}\n\n/**\n * Whether the Etch scripting API is present on the page. Use this to guard code\n * that should no-op when not running inside the builder.\n */\nexport function isEtchAvailable(): boolean {\n\treturn readEtch() !== undefined;\n}\n\n/** The major version number of a semver-ish string, or `null` if unparseable. */\nfunction majorOf(version: string): number | null {\n\tconst match = /^\\D*(\\d+)/.exec(version);\n\treturn match ? Number(match[1]) : null;\n}\n\n/**\n * Best-effort compatibility check for `0.x` runtimes that have no native\n * `connect()`. Warns (does not throw) when the requested major differs from the\n * runtime's, so experimental consumers aren't hard-blocked.\n */\nfunction warnIfIncompatible(requested: string, runtime: string): void {\n\tconst want = majorOf(requested);\n\tconst have = majorOf(runtime);\n\tif (want === null || have === null || want === have) return;\n\tconsole.warn(\n\t\t`[@digital-gravy/etch-public-api] Requested Etch API v${requested} but the ` +\n\t\t\t`page provides v${runtime}. Behavior may differ.`\n\t);\n}\n\n/**\n * Acquire the Etch scripting API from the page.\n *\n * The runtime lives on `window.etch` (injected by the builder); this returns it\n * typed. When the page exposes a future stable runtime with a native\n * `connect()`, version negotiation is delegated to it. On today's `0.x`\n * runtime, the global is returned directly after a best-effort version check.\n *\n * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.\n *\n * @example\n * ```ts\n * import { getEtch } from '@etchwp/public-api';\n *\n * const etch = getEtch();\n * const ids = etch.blocks.find({ type: 'text' });\n * etch.blocks.setText(ids[0], 'Hello');\n * await etch.saveAsync();\n * ```\n */\nexport function getEtch(options: ConnectOptions = {}): Etch {\n\tconst etch = readEtch();\n\tif (!etch) {\n\t\tthrow new EtchApiError(\n\t\t\t'NOT_AVAILABLE',\n\t\t\t'window.etch is not available. The Etch builder is not loaded on this page, ' +\n\t\t\t\t'or getEtch() ran before it finished initializing.'\n\t\t);\n\t}\n\n\tif (typeof etch.connect === 'function') {\n\t\treturn etch.connect(options);\n\t}\n\n\tif (options.apiVersion) {\n\t\twarnIfIncompatible(\n\t\t\toptions.apiVersion,\n\t\t\tetch.apiVersion ?? ETCH_API_VERSION\n\t\t);\n\t}\n\treturn etch;\n}\n"]}

package/package.json

@@ -1,46 +1,60 @@
 {
-  "name": "@digital-gravy/etch-public-api",
-  "version": "0.6.0",
-  "description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run build"
-  },
-  "keywords": [
-    "etch",
-    "etchwp",
-    "wordpress",
-    "builder",
-    "scripting",
-    "api"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^3.0.5"
-  }
+	"name": "@digital-gravy/etch-public-api",
+	"version": "0.7.1",
+	"description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Digital-Gravy/etch-public-api.git"
+	},
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "bun run eslint && bun run format:check",
+		"eslint": "eslint .",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"prepublishOnly": "bun run build"
+	},
+	"keywords": [
+		"etch",
+		"etchwp",
+		"wordpress",
+		"builder",
+		"scripting",
+		"api"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.2",
+		"eslint": "^9.39.2",
+		"eslint-config-prettier": "^10.1.8",
+		"globals": "^17.1.0",
+		"prettier": "^3.8.1",
+		"tsup": "^8.3.5",
+		"typescript": "^5.7.2",
+		"typescript-eslint": "^8.53.1",
+		"vitest": "^3.0.5"
+	}
 }