@localess/client 3.0.0-dev.20260313114825 → 3.0.0-dev.20260323211059

package/README.md

@@ -303,8 +303,7 @@ Base type for all content schema data objects.
 ```ts
 interface ContentDataSchema {
   _id: string;
-  _schema?: string;
-  schema: string;
+  _schema: string;
 }
 
 interface ContentData extends ContentDataSchema {
@@ -374,6 +373,18 @@ A key-value map of translation keys to translated string values.
 
 ---
 
+## AI Coding Agents
+
+This package ships a [`SKILL.md`](./SKILL.md) file that provides AI coding agents (GitHub Copilot, Claude Code, Cursor, and others) with accurate, up-to-date APIs, patterns, and best practices. Most agents automatically read `SKILL.md` when starting a session.
+
+When you change the public API of this package, update `SKILL.md` alongside your code:
+
+- **New option or parameter** → add it to the relevant options table and usage example
+- **Changed behaviour** → update the description and any affected code snippets
+- **Deprecated API** → mark it clearly and point to the replacement
+
+---
+
 ## License
 
 [MIT](../../LICENSE)

package/SKILL.md

@@ -0,0 +1,282 @@
+# SKILL: @localess/client
+
+## Overview
+
+`@localess/client` is the **core JavaScript/TypeScript SDK** for the Localess headless CMS. It is a **server-side-only** library — never use it in browser/client-side code because it requires an API token that must remain secret.
+
+**Zero production dependencies.** Requires Node.js >= 20.0.0.
+
+---
+
+## Installation
+
+```bash
+npm install @localess/client
+```
+
+---
+
+## Initialization
+
+```typescript
+import { localessClient } from "@localess/client";
+
+const client = localessClient({
+  origin: 'https://my-localess.web.app',  // Full URL with protocol (required)
+  spaceId: 'YOUR_SPACE_ID',               // From Space settings (required)
+  token: 'YOUR_API_TOKEN',                // API token — NEVER expose client-side (required)
+  version: 'draft',                   // undefined = published (default), 'draft' for preview
+  debug: false,                           // Logs requests; default: false
+  cacheTTL: 300000,                       // Cache TTL in ms; false to disable; default: 5 min
+});
+```
+
+---
+
+## API Methods
+
+### Fetch Content by Slug
+
+```typescript
+const content = await client.getContentBySlug<Page>('home', {
+  locale: 'en',
+  resolveReference: true,  // Inline referenced content
+  resolveLink: true,        // Inline linked content
+  version: 'draft',         // Override client default per-request
+});
+// content.data is typed as Page
+```
+
+### Fetch Content by ID
+
+```typescript
+const content = await client.getContentById<Article>('content-id-here', {
+  locale: 'en',
+  resolveReference: true,
+});
+```
+
+### Fetch Navigation Links
+
+```typescript
+const links = await client.getLinks({
+  kind: 'DOCUMENT',          // 'DOCUMENT' | 'FOLDER'
+  parentSlug: 'blog',        // Filter to children of a slug
+  excludeChildren: false,    // Exclude nested sub-slugs
+});
+// links: { [id: string]: ContentMetadata }
+```
+
+### Fetch Translations
+
+```typescript
+const t = await client.getTranslations('en');
+// t: { [key: string]: string }
+// Usage: t['common.submit'] => 'Submit'
+```
+
+### Asset URL
+
+```typescript
+import { localessClient } from "@localess/client";
+
+const url = client.assetLink(content.data.image);
+// Returns: https://my-localess.web.app/api/v1/spaces/{spaceId}/assets/{uri}
+```
+
+---
+
+## Content Fetch Parameters
+
+| Parameter          | Type      | Default       | Description                            |
+|--------------------|-----------|---------------|----------------------------------------|
+| `version`          | `'draft' \| undefined` | `undefined`   | `'draft'` for preview, omit for published |
+| `locale`           | `string`  | —             | ISO 639-1 code: `'en'`, `'de'`, etc.  |
+| `resolveReference` | `boolean` | `false`       | Inline referenced content objects      |
+| `resolveLink`      | `boolean` | `false`       | Inline linked content metadata         |
+
+---
+
+## Caching
+
+- Default: TTL-based, **5 minutes** (300,000 ms)
+- Cache key = full request URL (includes all parameters)
+- Adjust for content update frequency:
+
+```typescript
+localessClient({ cacheTTL: 60000 })    // 1 minute — frequently updated
+localessClient({ cacheTTL: 3600000 })  // 1 hour   — rarely updated
+localessClient({ cacheTTL: false })    // Disabled  — always fresh (draft mode)
+```
+
+---
+
+## Visual Editor Integration
+
+### Inject Sync Script
+
+```typescript
+import { loadLocalessSync } from "@localess/client";
+
+// Call in browser context (e.g., inside useEffect or layout script)
+loadLocalessSync('https://my-localess.web.app');
+// Injects the Localess sync script into <head>; no-op if not in iframe
+```
+
+### Mark Elements as Editable
+
+```typescript
+import { localessEditable, localessEditableField } from "@localess/client";
+
+// Root element of a content block
+<section {...localessEditable(data)}>
+  {/* Adds: data-ll-id (from _id), data-ll-schema (from _schema) */}
+
+  {/* Individual editable field */}
+  <h1 {...localessEditableField<Page>('title')}>
+    {/* Adds: data-ll-field="title" */}
+    {data.title}
+  </h1>
+</section>
+```
+
+> **Note:** `localessEditable` reads `content._id` and `content._schema`.
+
+### Listen to Editor Events
+
+```typescript
+// Only available when app is loaded inside the Localess Visual Editor iframe
+if (window.localess) {
+  window.localess.on(['input', 'change'], (event) => {
+    if (event.type === 'input' || event.type === 'change') {
+      setPageData(event.data); // Real-time preview update
+    }
+  });
+  // No .off() method — subscribe once on mount
+}
+```
+
+**Event types:**
+
+| Event         | When                                        |
+|---------------|---------------------------------------------|
+| `input`       | User is typing in a field (real-time)       |
+| `change`      | Field value confirmed                       |
+| `save`        | Content saved                               |
+| `publish`     | Content published                           |
+| `pong`        | Editor heartbeat response                   |
+| `enterSchema` | User enters a schema element                |
+| `hoverSchema` | User hovers over a schema element           |
+
+---
+
+## Key Data Types
+
+```typescript
+// Content response wrapper
+interface Content<T extends ContentData> extends ContentMetadata {
+  data?: T;
+  links?: Links;
+  references?: References;
+}
+
+// Base schema fields every content data object has
+interface ContentDataSchema {
+  _id: string;
+  _schema: string;
+}
+
+// Asset reference
+interface ContentAsset {
+  kind: 'ASSET';
+  uri: string;
+}
+
+// Internal or external link
+interface ContentLink {
+  kind: 'LINK';
+  type: 'url' | 'content';
+  target: '_blank' | '_self';
+  uri: string;
+}
+
+// Rich text (Tiptap JSON format)
+interface ContentRichText {
+  type?: string;
+  content?: ContentRichText[];
+}
+
+// Reference to another content item
+interface ContentReference {
+  kind: 'REFERENCE';
+  uri: string;
+}
+
+// Navigation links map
+interface Links {
+  [contentId: string]: ContentMetadata;
+}
+
+// Translations flat map
+interface Translations {
+  [key: string]: string;
+}
+```
+
+---
+
+## Environment Safety Utilities
+
+```typescript
+import { isBrowser, isServer, isIframe } from "@localess/client";
+
+isBrowser()  // true if window is defined
+isServer()   // true if window is undefined
+isIframe()   // true if running inside an iframe (browser only)
+```
+
+---
+
+## Best Practices
+
+1. **Never import `@localess/client` in browser bundles.** Use it only in server-side code: Next.js Server Components, API routes, `getServerSideProps`, Remix loaders, etc.
+
+2. **Store credentials in environment variables**, not hardcoded:
+   ```
+   LOCALESS_ORIGIN=https://my-localess.web.app
+   LOCALESS_SPACE_ID=your-space-id
+   LOCALESS_TOKEN=your-api-token
+   ```
+
+3. **Create one client instance** and reuse it — the cache is instance-bound.
+
+4. **Use generated types** from `@localess/cli` (`localess types generate`) for full type safety:
+   ```typescript
+   import type { Page } from './.localess/localess';
+   const content = await client.getContentBySlug<Page>('home');
+   ```
+
+5. **Use `version: 'draft'` and `cacheTTL: false` for preview/editing** environments.
+
+6. **Use `resolveReference: true`** only when you need inline reference data — it increases payload size.
+
+---
+
+## Exports Reference
+
+```typescript
+export { localessClient }                          // Client factory
+export { localessEditable, localessEditableField } // Visual editor helpers
+export { llEditable, llEditableField }             // Deprecated aliases
+export { loadLocalessSync }                        // Sync script injector
+export { isBrowser, isServer, isIframe }           // Environment utilities
+export type {
+  LocalessClient, LocalessClientOptions,
+  ContentFetchParams, LinksFetchParams,
+  Content, ContentData, ContentDataSchema, ContentDataField,
+  ContentMetadata, ContentAsset, ContentLink,
+  ContentRichText, ContentReference,
+  Links, References, Translations,
+  LocalessSync, EventToApp, EventCallback, EventToAppType,
+}
+```

package/dist/index.d.mts

@@ -74,11 +74,7 @@ interface ContentDataSchema {
     /**
      * Unique identifier for the Schema object.
      */
-    _schema?: string;
-    /**
-     * Unique identifier for the Schema object.
-     */
-    schema: string;
+    _schema: string;
 }
 /**
  * ContentData defined Object to connect all possible root Schemas.
@@ -233,7 +229,7 @@ type ContentFetchParams = {
      * Content version to fetch, leave empty for 'published' or 'draft' for the latest draft.
      * Overrides the version set in the client options.
      */
-    version?: 'draft' | string;
+    version?: 'draft';
     /**
      * Locale identifier (ISO 639-1) to fetch content in, leave empty for default locale.
      *
@@ -293,16 +289,6 @@ declare function localessEditable(content: ContentDataSchema): {
     'data-ll-id': string;
     'data-ll-schema': string;
 };
-/**
- * Adds Localess editable attributes to a content item.
- * @param content
- * @returns An object containing data-ll-id and data-ll-schema attributes.
- * @deprecated use localessEditable instead
- */
-declare function llEditable(content: ContentDataSchema): {
-    'data-ll-id': string;
-    'data-ll-schema': string;
-};
 /**
  * Adds Localess editable field attribute to a specific field.
  * Added type safety to ensure fieldName is a valid key of the content data excluding base schema fields.
@@ -312,15 +298,6 @@ declare function llEditable(content: ContentDataSchema): {
 declare function localessEditableField<T extends ContentData = ContentData>(fieldName: Exclude<keyof T, keyof ContentDataSchema>): {
     'data-ll-field': Exclude<keyof T, keyof ContentDataSchema>;
 };
-/**
- * Adds Localess editable field attribute to a specific field.
- * @param fieldName
- * @returns An object containing data-ll-field attribute.
- * @deprecated use localessEditableField instead
- */
-declare function llEditableField(fieldName: string): {
-    'data-ll-field': string;
-};
 
 /**
  * Inject Localess Sync Script in Header
@@ -356,4 +333,4 @@ declare global {
     }
 }
 
-export { type Content, type ContentAsset, type ContentData, type ContentDataField, type ContentDataSchema, type ContentFetchParams, type ContentLink, type ContentMetadata, type ContentReference, type ContentRichText, type EventCallback, type EventToApp, type EventToAppType, type Links, type LinksFetchParams, type Locale, type LocalessClient, type LocalessClientOptions, type LocalessSync, type References, type Translations, isBrowser, isIframe, isServer, llEditable, llEditableField, loadLocalessSync, localessClient, localessEditable, localessEditableField };
+export { type Content, type ContentAsset, type ContentData, type ContentDataField, type ContentDataSchema, type ContentFetchParams, type ContentLink, type ContentMetadata, type ContentReference, type ContentRichText, type EventCallback, type EventToApp, type EventToAppType, type Links, type LinksFetchParams, type Locale, type LocalessClient, type LocalessClientOptions, type LocalessSync, type References, type Translations, isBrowser, isIframe, isServer, loadLocalessSync, localessClient, localessEditable, localessEditableField };

package/dist/index.d.ts

@@ -74,11 +74,7 @@ interface ContentDataSchema {
     /**
      * Unique identifier for the Schema object.
      */
-    _schema?: string;
-    /**
-     * Unique identifier for the Schema object.
-     */
-    schema: string;
+    _schema: string;
 }
 /**
  * ContentData defined Object to connect all possible root Schemas.
@@ -233,7 +229,7 @@ type ContentFetchParams = {
      * Content version to fetch, leave empty for 'published' or 'draft' for the latest draft.
      * Overrides the version set in the client options.
      */
-    version?: 'draft' | string;
+    version?: 'draft';
     /**
      * Locale identifier (ISO 639-1) to fetch content in, leave empty for default locale.
      *
@@ -293,16 +289,6 @@ declare function localessEditable(content: ContentDataSchema): {
     'data-ll-id': string;
     'data-ll-schema': string;
 };
-/**
- * Adds Localess editable attributes to a content item.
- * @param content
- * @returns An object containing data-ll-id and data-ll-schema attributes.
- * @deprecated use localessEditable instead
- */
-declare function llEditable(content: ContentDataSchema): {
-    'data-ll-id': string;
-    'data-ll-schema': string;
-};
 /**
  * Adds Localess editable field attribute to a specific field.
  * Added type safety to ensure fieldName is a valid key of the content data excluding base schema fields.
@@ -312,15 +298,6 @@ declare function llEditable(content: ContentDataSchema): {
 declare function localessEditableField<T extends ContentData = ContentData>(fieldName: Exclude<keyof T, keyof ContentDataSchema>): {
     'data-ll-field': Exclude<keyof T, keyof ContentDataSchema>;
 };
-/**
- * Adds Localess editable field attribute to a specific field.
- * @param fieldName
- * @returns An object containing data-ll-field attribute.
- * @deprecated use localessEditableField instead
- */
-declare function llEditableField(fieldName: string): {
-    'data-ll-field': string;
-};
 
 /**
  * Inject Localess Sync Script in Header
@@ -356,4 +333,4 @@ declare global {
     }
 }
 
-export { type Content, type ContentAsset, type ContentData, type ContentDataField, type ContentDataSchema, type ContentFetchParams, type ContentLink, type ContentMetadata, type ContentReference, type ContentRichText, type EventCallback, type EventToApp, type EventToAppType, type Links, type LinksFetchParams, type Locale, type LocalessClient, type LocalessClientOptions, type LocalessSync, type References, type Translations, isBrowser, isIframe, isServer, llEditable, llEditableField, loadLocalessSync, localessClient, localessEditable, localessEditableField };
+export { type Content, type ContentAsset, type ContentData, type ContentDataField, type ContentDataSchema, type ContentFetchParams, type ContentLink, type ContentMetadata, type ContentReference, type ContentRichText, type EventCallback, type EventToApp, type EventToAppType, type Links, type LinksFetchParams, type Locale, type LocalessClient, type LocalessClientOptions, type LocalessSync, type References, type Translations, isBrowser, isIframe, isServer, loadLocalessSync, localessClient, localessEditable, localessEditableField };

package/dist/index.js

@@ -23,8 +23,6 @@ __export(index_exports, {
   isBrowser: () => isBrowser,
   isIframe: () => isIframe,
   isServer: () => isServer,
-  llEditable: () => llEditable,
-  llEditableField: () => llEditableField,
   loadLocalessSync: () => loadLocalessSync,
   localessClient: () => localessClient,
   localessEditable: () => localessEditable,
@@ -253,13 +251,7 @@ function localessClient(options) {
 function localessEditable(content) {
   return {
     "data-ll-id": content._id,
-    "data-ll-schema": content._schema || content.schema
-  };
-}
-function llEditable(content) {
-  return {
-    "data-ll-id": content._id,
-    "data-ll-schema": content._schema || content.schema
+    "data-ll-schema": content._schema
   };
 }
 function localessEditableField(fieldName) {
@@ -267,11 +259,6 @@ function localessEditableField(fieldName) {
     "data-ll-field": fieldName
   };
 }
-function llEditableField(fieldName) {
-  return {
-    "data-ll-field": fieldName
-  };
-}
 
 // src/sync.ts
 var JS_SYNC_ID = "localess-js-sync";
@@ -296,8 +283,6 @@ function loadLocalessSync(origin, force = false) {
   isBrowser,
   isIframe,
   isServer,
-  llEditable,
-  llEditableField,
   loadLocalessSync,
   localessClient,
   localessEditable,

package/dist/index.mjs

@@ -219,13 +219,7 @@ function localessClient(options) {
 function localessEditable(content) {
   return {
     "data-ll-id": content._id,
-    "data-ll-schema": content._schema || content.schema
-  };
-}
-function llEditable(content) {
-  return {
-    "data-ll-id": content._id,
-    "data-ll-schema": content._schema || content.schema
+    "data-ll-schema": content._schema
   };
 }
 function localessEditableField(fieldName) {
@@ -233,11 +227,6 @@ function localessEditableField(fieldName) {
     "data-ll-field": fieldName
   };
 }
-function llEditableField(fieldName) {
-  return {
-    "data-ll-field": fieldName
-  };
-}
 
 // src/sync.ts
 var JS_SYNC_ID = "localess-js-sync";
@@ -261,8 +250,6 @@ export {
   isBrowser,
   isIframe,
   isServer,
-  llEditable,
-  llEditableField,
   loadLocalessSync,
   localessClient,
   localessEditable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localess/client",
-  "version": "3.0.0-dev.20260313114825",
+  "version": "3.0.0-dev.20260323211059",
   "description": "Universal JavaScript/TypeScript SDK for Localess's API.",
   "keywords": [
     "localess",
@@ -14,7 +14,8 @@
   "homepage": "https://github.com/Lessify/localess-js",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "main": "dist/index.js",
   "module": "dist/index.mjs",