@no-mess/client 0.2.0 → 0.4.0

package/README.md

@@ -10,65 +10,119 @@ npm install @no-mess/client
 bun add @no-mess/client
 ```
 
-## Usage
-
-### Fetching content
+## Fetch Content
 
 ```ts
 import { createNoMessClient } from "@no-mess/client";
 
 const client = createNoMessClient({
-  apiKey: "your-api-key",
+  apiKey: process.env.NO_MESS_API_KEY!,
 });
 
-// Get all entries of a content type
 const posts = await client.getEntries("blog-post");
-
-// Get a single entry by slug
 const post = await client.getEntry("blog-post", "hello-world");
 ```
 
-### Live preview (React)
+## Preview-Only Route
+
+Use this when you want a dedicated `/no-mess-preview` page.
 
 ```tsx
-import { useNoMessPreview } from "@no-mess/client/react";
+"use client";
+
+import { NoMessPreview } from "@no-mess/client/react";
+
+export default function PreviewPage() {
+  return (
+    <NoMessPreview apiKey={process.env.NEXT_PUBLIC_NO_MESS_PUBLISHABLE_KEY!}>
+      {({ entry, error, isLoading }) => {
+        if (isLoading) return <p>Loading preview...</p>;
+        if (error) return <p>{error.message}</p>;
+        if (!entry) return null;
+
+        return <h1>{entry.title}</h1>;
+      }}
+    </NoMessPreview>
+  );
+}
+```
 
-function PreviewPage() {
-  const { entry, isLoading, error } = useNoMessPreview({
-    apiKey: "your-api-key",
-  });
+## Route-Aware Preview and Live Edit
 
-  if (isLoading) return <p>Loading preview...</p>;
-  if (error) return <p>Error: {error.message}</p>;
+This is the recommended integration path. It lets the dashboard open real site
+routes, apply unsaved iframe-only edits before publish, and store reported
+delivery URLs per entry.
 
-  return <h1>{entry?.fields.title}</h1>;
+### 1. Wrap the route tree
+
+```tsx
+"use client";
+
+import { NoMessLiveRouteProvider } from "@no-mess/client/react";
+
+export default function SiteLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <NoMessLiveRouteProvider
+      apiKey={process.env.NEXT_PUBLIC_NO_MESS_PUBLISHABLE_KEY!}
+    >
+      {children}
+    </NoMessLiveRouteProvider>
+  );
 }
 ```
 
-The `useNoMessPreview` hook handles the postMessage handshake between the no-mess admin dashboard and your preview iframe automatically.
-
-### Shopify data
+### 2. Bind the rendered entry
 
-```ts
-const products = await client.getProducts();
-const product = await client.getProduct("product-handle");
-const collections = await client.getCollections();
-const collection = await client.getCollection("collection-handle");
+```tsx
+"use client";
+
+import {
+  NoMessField,
+  useNoMessEditableEntry,
+} from "@no-mess/client/react";
+
+export function BlogArticle({ entry }) {
+  const editableEntry = useNoMessEditableEntry(entry);
+
+  return (
+    <article>
+      <NoMessField as="h1" name="title">
+        {editableEntry.title}
+      </NoMessField>
+      <NoMessField as="div" name="body">
+        {editableEntry.body}
+      </NoMessField>
+    </article>
+  );
+}
 ```
 
-## Configuration
+`useNoMessEditableEntry()` automatically:
+- swaps in draft content for the active iframe session
+- applies unsaved field overrides from Live Edit
+- reports the current URL for route-aware reopening
+- emits the entry-bound signal used by dashboard warnings
+
+## Manual Route Reporting
+
+If you need custom reporting logic, call the client method directly:
 
 ```ts
+import { createNoMessClient } from "@no-mess/client";
+
 const client = createNoMessClient({
-  apiKey: "nm_...",           // Required — secret or publishable key
-  apiUrl: "https://...",      // Optional — defaults to https://api.no-mess.xyz
+  apiKey: process.env.NEXT_PUBLIC_NO_MESS_PUBLISHABLE_KEY!,
 });
-```
-
-### API Key Types
 
-- **Secret keys** (`nm_...`) — Full access. Use server-side only.
-- **Publishable keys** (`nm_pub_...`) — Read-only access to published content. Safe for client-side use.
+await client.reportLiveEditRoute({
+  entryId: "entry_123",
+  url: window.location.href,
+});
+```
 
 ## API Reference
 
@@ -81,108 +135,37 @@ const client = createNoMessClient({
 | `client.getEntries(contentType)` | Fetch all published entries of a content type |
 | `client.getEntry(contentType, slug)` | Get a single entry by slug |
 
-### Shopify
+### Preview / Live Edit
 
 | Method | Description |
 |--------|-------------|
-| `client.getProducts()` | List all synced Shopify products |
-| `client.getProduct(handle)` | Get a product by handle |
-| `client.getCollections()` | List all synced Shopify collections |
-| `client.getCollection(handle)` | Get a collection by handle |
+| `client.exchangePreviewSession(session)` | Exchange a preview session token for draft content |
+| `client.reportLiveEditRoute({ entryId, url? })` | Report the current delivery URL for route-aware Live Edit |
 
-### Preview
+### React (`@no-mess/client/react`)
 
-| Method | Description |
-|--------|-------------|
-| `client.exchangePreviewSession(session)` | Exchange a preview session token (HMAC-SHA256 auth) |
-
-### React Hooks (`@no-mess/client/react`)
-
-| Hook | Description |
-|------|-------------|
-| `useNoMessPreview(config)` | Subscribe to live preview updates in an iframe |
-| `useNoMessLiveEdit(config)` | Enable live editing with field-level updates |
-
-## Schema Builder
-
-The `@no-mess/client/schema` export provides helpers for defining content type schemas in code. Used by the [no-mess CLI](../no-mess-cli) to push and pull schemas.
-
-```ts
-import { defineSchema, defineContentType, field } from "@no-mess/client/schema";
-
-export default defineSchema({
-  contentTypes: [
-    defineContentType("blog-post", {
-      name: "Blog Post",
-      description: "Articles for the blog",
-      fields: {
-        title: field.text({ required: true }),
-        body: field.textarea({ required: true }),
-        heroImage: field.image(),
-        publishedAt: field.datetime(),
-        featured: field.boolean(),
-        externalUrl: field.url(),
-        category: field.select({
-          choices: [
-            { label: "Tech", value: "tech" },
-            { label: "Design", value: "design" },
-          ],
-        }),
-        relatedProduct: field.shopifyProduct(),
-        featuredCollection: field.shopifyCollection(),
-      },
-    }),
-  ],
-});
-```
+| API | Description |
+|-----|-------------|
+| `NoMessPreview` | Preview-only route wrapper |
+| `useNoMessPreview(config)` | Hook alternative for preview-only pages |
+| `NoMessLiveRouteProvider` | Route-aware provider for real site routes |
+| `useNoMessEditableEntry(entry, options?)` | Returns the active draft entry and reports the route |
+| `NoMessField` | Convenience component for `data-no-mess-field` annotations |
+| `useNoMessField(fieldName)` | Read a single field override from provider context |
 
-### Field Types
+## Migration
 
-| Builder | Type | Description |
-|---------|------|-------------|
-| `field.text()` | `text` | Plain text input |
-| `field.textarea()` | `textarea` | Multi-line text |
-| `field.number()` | `number` | Numeric value |
-| `field.boolean()` | `boolean` | True/false toggle |
-| `field.datetime()` | `datetime` | Date/time picker |
-| `field.url()` | `url` | URL field |
-| `field.image()` | `image` | Image upload |
-| `field.select(opts)` | `select` | Dropdown with choices (requires `choices` array) |
-| `field.shopifyProduct()` | `shopifyProduct` | Shopify product reference |
-| `field.shopifyCollection()` | `shopifyCollection` | Shopify collection reference |
-
-### Field Options
-
-All field builders accept an options object:
-
-```ts
-field.text({
-  required: true,        // Whether the field is required (default: false)
-  description: "...",    // Help text shown in the dashboard
-})
-```
-
-The `select` builder additionally requires a `choices` array:
-
-```ts
-field.select({
-  required: true,
-  choices: [
-    { label: "Draft", value: "draft" },
-    { label: "Published", value: "published" },
-  ],
-})
-```
+If you already use `useNoMessPreview()` and `useNoMessLiveEdit()` on
+`/no-mess-preview`:
 
-### Schema Utilities
+1. Keep the existing preview route in place.
+2. Add `NoMessLiveRouteProvider` to the real route tree.
+3. Replace direct entry rendering with `useNoMessEditableEntry(entry)` on the
+   routes you want Live Edit to open.
+4. Add `data-no-mess-field` annotations or `NoMessField` wrappers.
 
-| Function | Description |
-|----------|-------------|
-| `defineSchema({ contentTypes })` | Define a complete schema with content types |
-| `defineContentType(slug, options)` | Define a single content type |
-| `parseSchemaSource(source)` | Parse a schema.ts source string into a schema definition |
-| `generateSchemaSource(schema)` | Generate schema.ts source from a schema definition |
-| `generateContentTypeSource(contentType)` | Generate source for a single content type |
+If you do nothing, the legacy preview route keeps working. You only miss the
+route-aware Live Edit workflow.
 
 ## License
 

package/dist/client.d.ts

@@ -1,9 +1,12 @@
-import type { GetEntryOptions, NoMessClientConfig, NoMessEntry, PreviewExchangeResult, PreviewSessionAuth, SchemaGetResponse, SchemaListResponse, ShopifyCollection, ShopifyProduct } from "./types.js";
+import type { GetEntryOptions, NoMessClientConfig, NoMessEntry, PreviewExchangeResult, PreviewSessionAuth, ReportLiveEditRouteOptions, SchemaGetResponse, SchemaListResponse, ShopifyCollection, ShopifyProduct } from "./types.js";
 export declare class NoMessClient {
     private apiUrl;
     private apiKey;
+    private logger;
     constructor(config: NoMessClientConfig);
-    private fetch;
+    private emitErrorLog;
+    private readResponseText;
+    private request;
     /**
      * List all content type schemas with fields, TypeScript interfaces, and entry counts.
      */
@@ -42,10 +45,17 @@ export declare class NoMessClient {
      * Computes an HMAC-SHA256 proof and sends it to the server for verification.
      */
     exchangePreviewSession(session: PreviewSessionAuth): Promise<PreviewExchangeResult>;
+    /**
+     * Report that an entry is rendered on the current site URL for route-aware live edit.
+     */
+    reportLiveEditRoute(options: ReportLiveEditRouteOptions): Promise<{
+        ok: boolean;
+    }>;
     /**
      * Compute HMAC-SHA256 proof for preview session authentication.
      * Uses Web Crypto API (works in browsers, Node.js 18+, Deno, Bun, edge runtimes).
      */
     private computeProof;
+    private toBase64;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,kBAAkB;YAiBxB,KAAK;IA+BnB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI/C;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI7D;;OAEG;IACG,UAAU,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAClD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,EAAE,CAAC;IAIf;;;OAGG;IACG,QAAQ,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAChD,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,CAAC,CAAC;IAWb;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAI9C;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAIzD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAIpD;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI/D;;;OAGG;IACG,sBAAsB,CAC1B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC;IAkCjC;;;OAGG;YACW,YAAY;CA0B3B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,WAAW,EAEX,qBAAqB,EACrB,kBAAkB,EAClB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAWpB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAqC;gBAEvC,MAAM,EAAE,kBAAkB;IAyBtC,OAAO,CAAC,YAAY;YAyBN,gBAAgB;YA6BhB,OAAO;IAoGrB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAQ/C;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAQ7D;;OAEG;IACG,UAAU,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAClD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,EAAE,CAAC;IAQf;;;OAGG;IACG,QAAQ,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAChD,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,CAAC,CAAC;IAiBb;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAQ9C;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAQzD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAQpD;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAQ/D;;;OAGG;IACG,sBAAsB,CAC1B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC;IAoBjC;;OAEG;IACG,mBAAmB,CACvB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAS3B;;;OAGG;YACW,YAAY;IA8F1B,OAAO,CAAC,QAAQ;CAmBjB"}