@localess/client 0.9.2-dev.20260216094809

package/README.md

@@ -0,0 +1,62 @@
+<br/>
+<br/>
+<img src="https://github.com/Lessify/localess/wiki/img/logo-adaptive.svg" alt="logo">
+<br/>
+<br/>
+
+----
+
+# Localess JavaScript / TypeScript Client SDK
+
+This client SDK is designed to work with the Localess API. It provides a simple way to interact with the Localess API from your JavaScript or TypeScript application.
+
+> **Important:** 
+> The Client is designed to be used on the server side only, as it requires your **Localess API Token** to be kept secret.
+> Do not use this client in your frontend application, as it exposes your API Token to the public.
+
+## Installation
+
+### NPM
+````bash
+npm install @localess/client@latest
+````
+
+### Yarn
+````bash
+yarn add @localess/client@latest
+````
+
+## Client
+
+````ts
+import {localessClient} from "@localess/client";
+
+const llClient = localessClient({
+  // A fully qualified domain name with protocol (http/https) and port.
+  origin: 'https://my-localess.web.app',
+  // Localess space ID, cna be found in the Localess Space settings
+  spaceId: 'I1LoVe2LocaLess4Rever',
+  // Localess API token, can be found in the Localess Space settings
+  token: 'Baz00KaT0KeN8S3CureLL'
+});
+
+// Fetch all Content Links
+llClient.getLinks()
+// Fetch content by SLUG
+llClient.getContentBySlug('docs/overview')
+// Fetch content by ID
+llClient.getContentById('FRnIT7CUABoRCdSVVGGs')
+// Fetch translations by locale
+llClient.getTranslations('en') 
+````
+
+## Sync with Visual Editor
+
+It will automatically inject Localess Sync Script in to the HTML page.
+
+````ts
+import {loadLocalessSync} from "@localess/client";
+
+// A fully qualified domain name with protocol (http/https) and port.
+loadLocalessSync('https://my-localess.web.app')
+````

package/dist/index.d.mts

@@ -0,0 +1,359 @@
+/**
+ * Content Asset defines reference to an Asset.
+ */
+interface ContentAsset {
+    /**
+     * Define the type of Asset
+     */
+    kind: 'ASSET';
+    /**
+     * Unique identifier for the asset.
+     */
+    uri: string;
+}
+
+/**
+ * Content Link define reference to a Link.
+ */
+interface ContentLink {
+    /**
+     * Define the type of Link
+     */
+    kind: 'LINK';
+    /**
+     * Define the target of the link. _blank for the new tab and _self for the same tab.
+     */
+    target: '_blank' | '_self';
+    /**
+     * Define the type of Link. URL for external links and Content for internal links.
+     */
+    type: 'url' | 'content';
+    /**
+     * If the type is content, then it will be Content ID. Otherwise, it will be URL.
+     */
+    uri: string;
+}
+
+/**
+ * Content RichText define content as JSON Object.
+ */
+interface ContentRichText {
+    /**
+     * Define the type of Content Node
+     */
+    type?: string;
+    /**
+     * List of Content Nodes
+     */
+    content?: ContentRichText[];
+}
+
+/**
+ * Content Reference defines reference to a Content.
+ */
+interface ContentReference {
+    /**
+     * Define the type of REFERENCE
+     */
+    kind: 'REFERENCE';
+    /**
+     * Unique identifier for the Content Document.
+     */
+    uri: string;
+}
+
+type ContentDataField = any | string | string[] | number | boolean | ContentLink | ContentRichText | ContentData | ContentData[] | ContentAsset | ContentAsset[] | ContentReference | ContentReference[];
+/**
+ * Content Data Schema related information.
+ */
+interface ContentDataSchema {
+    /**
+     * Unique identifier of a component in a content.
+     */
+    _id: string;
+    /**
+     * Unique identifier for the Schema object.
+     */
+    _schema?: string;
+    /**
+     * Unique identifier for the Schema object.
+     */
+    schema: string;
+}
+/**
+ * ContentData defined Object to connect all possible root Schemas.
+ */
+interface ContentData extends ContentDataSchema {
+    /**
+     * Other Schema-specific fields
+     */
+    [field: string]: ContentDataField | undefined;
+}
+
+/**
+ * Content Metadata defines short information about a Content for navigation reason.
+ */
+interface ContentMetadata {
+    /**
+     * Date and Time at which the Content was created.
+     */
+    createdAt: string;
+    /**
+     * Combination of SLUG and Parent SLUG of the Content
+     */
+    fullSlug: string;
+    /**
+     * Unique identifier for the object.
+     */
+    id: string;
+    /**
+     * Define the type of Content, whether it is a FOLDER or DOCUMENT.
+     */
+    kind: 'FOLDER' | 'DOCUMENT';
+    /**
+     * Name of the Content
+     */
+    name: string;
+    /**
+     * Parent SLUG of the Content
+     */
+    parentSlug: string;
+    /**
+     * Date and Time at which the Content was published.
+     */
+    publishedAt?: string;
+    /**
+     * SLUG of the Content
+     */
+    slug: string;
+    /**
+     * Date and Time at which the Content was updated.
+     */
+    updatedAt: string;
+}
+
+/**
+ * Key-Value Object. Where Key is a Unique identifier for the Content object and Value is Content Metadata.
+ */
+interface Links {
+    [key: string]: ContentMetadata;
+}
+
+/**
+ * Key-Value Object. Where Key is a Unique identifier for the Content object and Value is Content.
+ */
+interface References {
+    [key: string]: Content;
+}
+
+/**
+ * Content defines a shared object for all possible Content Types.
+ */
+interface Content<T extends ContentData = ContentData> extends ContentMetadata {
+    /**
+     * Content Data
+     */
+    data?: T;
+    /**
+     * All links used in the content.
+     */
+    links?: Links;
+    /**
+     * All references used in the content.
+     */
+    references?: References;
+}
+
+interface Locale {
+    /**
+     * Unique identifier for the Locale.
+     */
+    id: string;
+    /**
+     * Name of the Locale.
+     */
+    name: string;
+}
+
+/**
+ * Key-Value Object. Where Key is Translation ID and Value is Translated Content
+ */
+interface Translations {
+    [key: string]: string;
+}
+
+type LocalessClientOptions = {
+    /**
+     * A fully qualified domain name with protocol (http/https) and port.
+     *
+     * Example: https://my-localess.web.app
+     */
+    origin: string;
+    /**
+     * Localess space ID can be found in the Localess Space settings
+     */
+    spaceId: string;
+    /**
+     * Localess API token can be found in the Localess Space settings
+     */
+    token: string;
+    /**
+     * Content version to fetch, leave empty for 'published' or 'draft' for the latest draft
+     */
+    version?: 'draft' | string;
+    /**
+     * Enable debug mode
+     */
+    debug?: boolean;
+    /**
+     * Cache TTL (time to live) for API responses. Default is 5 minutes (300000 ms).
+     * Set to false to disable caching.
+     */
+    cacheTTL?: number | false;
+};
+type LinksFetchParams = {
+    /**
+     * Content Kind. FOLDER or DOCUMENT. If not provided, it will return all.
+     * @example 'DOCUMENT'
+     */
+    kind?: 'DOCUMENT' | 'FOLDER';
+    /**
+     * Content parent slug.
+     * @example 'legal/policy'
+     */
+    parentSlug?: string;
+    /**
+     * If **true**, exclude all sub slugs, otherwise include all content under current selected **parent slug**.
+     * @example false
+     */
+    excludeChildren?: boolean;
+};
+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;
+    /**
+     * Locale identifier (ISO 639-1) to fetch content in, leave empty for default locale.
+     *
+     * Example: en
+     */
+    locale?: string;
+    /**
+     * Resolve references in the content data. Default is false.
+     */
+    resolveReference?: boolean;
+    /**
+     * Resolve links in the content data. Default is false.
+     */
+    resolveLink?: boolean;
+};
+interface LocalessClient {
+    /**
+     * Get all links
+     * @param params{LinksFetchParams} - Fetch parameters
+     * @returns {Promise<Links>}
+     */
+    getLinks(params?: LinksFetchParams): Promise<Links>;
+    /**
+     * Get content by SLUG
+     * @param slug{string} - Content SLUG
+     * @param params{ContentFetchParams} - Fetch parameters
+     * @returns {Promise<Content>}
+     */
+    getContentBySlug<T extends ContentData = ContentData>(slug: string, params?: ContentFetchParams): Promise<Content<T>>;
+    /**
+     * Get content by ID
+     * @param id{string} - Content ID
+     * @param params{ContentFetchParams} - Fetch parameters
+     * @returns {Promise<Content>}
+     */
+    getContentById<T extends ContentData = ContentData>(id: string, params?: ContentFetchParams): Promise<Content<T>>;
+    /**
+     * Get translations for the given locale
+     * @param locale{string} - Locale identifier (ISO 639-1)
+     */
+    getTranslations(locale: string): Promise<Translations>;
+    syncScriptUrl(): string;
+    assetLink(asset: ContentAsset | string): string;
+}
+/**
+ * Create a Localess API Client
+ * @param {LocalessClientOptions} options connection details
+ */
+declare function localessClient(options: LocalessClientOptions): LocalessClient;
+
+/**
+ * Adds Localess editable attributes to a content item.
+ * @param content
+ * @returns An object containing data-ll-id and data-ll-schema attributes.
+ */
+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.
+ * @param fieldName
+ * @returns An object containing data-ll-field attribute.
+ */
+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
+ * @param {string} origin A fully qualified domain name with protocol (http/https) and port.
+ * @param {boolean} force Force Script Injection even if the application is not in Visual Editor.
+ */
+declare function loadLocalessSync(origin: string, force?: boolean): void;
+
+declare const isBrowser: () => boolean;
+declare const isServer: () => boolean;
+declare const isIframe: () => boolean;
+
+type EventToAppType = 'save' | 'publish' | 'pong' | 'input' | 'change' | 'enterSchema' | 'hoverSchema';
+type EventCallback = (event: EventToApp) => void;
+type EventToApp = {
+    type: 'save' | 'publish' | 'pong';
+} | {
+    type: 'input' | 'change';
+    data: any;
+} | {
+    type: 'enterSchema' | 'hoverSchema';
+    id: string;
+    schema: string;
+    field?: string;
+};
+interface LocalessSync {
+    onChange: (callback: EventCallback) => void;
+    on: (event: EventToAppType | EventToAppType[], callback: EventCallback) => void;
+}
+declare global {
+    interface Window {
+        localess?: LocalessSync;
+    }
+}
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+/**
+ * Content Asset defines reference to an Asset.
+ */
+interface ContentAsset {
+    /**
+     * Define the type of Asset
+     */
+    kind: 'ASSET';
+    /**
+     * Unique identifier for the asset.
+     */
+    uri: string;
+}
+
+/**
+ * Content Link define reference to a Link.
+ */
+interface ContentLink {
+    /**
+     * Define the type of Link
+     */
+    kind: 'LINK';
+    /**
+     * Define the target of the link. _blank for the new tab and _self for the same tab.
+     */
+    target: '_blank' | '_self';
+    /**
+     * Define the type of Link. URL for external links and Content for internal links.
+     */
+    type: 'url' | 'content';
+    /**
+     * If the type is content, then it will be Content ID. Otherwise, it will be URL.
+     */
+    uri: string;
+}
+
+/**
+ * Content RichText define content as JSON Object.
+ */
+interface ContentRichText {
+    /**
+     * Define the type of Content Node
+     */
+    type?: string;
+    /**
+     * List of Content Nodes
+     */
+    content?: ContentRichText[];
+}
+
+/**
+ * Content Reference defines reference to a Content.
+ */
+interface ContentReference {
+    /**
+     * Define the type of REFERENCE
+     */
+    kind: 'REFERENCE';
+    /**
+     * Unique identifier for the Content Document.
+     */
+    uri: string;
+}
+
+type ContentDataField = any | string | string[] | number | boolean | ContentLink | ContentRichText | ContentData | ContentData[] | ContentAsset | ContentAsset[] | ContentReference | ContentReference[];
+/**
+ * Content Data Schema related information.
+ */
+interface ContentDataSchema {
+    /**
+     * Unique identifier of a component in a content.
+     */
+    _id: string;
+    /**
+     * Unique identifier for the Schema object.
+     */
+    _schema?: string;
+    /**
+     * Unique identifier for the Schema object.
+     */
+    schema: string;
+}
+/**
+ * ContentData defined Object to connect all possible root Schemas.
+ */
+interface ContentData extends ContentDataSchema {
+    /**
+     * Other Schema-specific fields
+     */
+    [field: string]: ContentDataField | undefined;
+}
+
+/**
+ * Content Metadata defines short information about a Content for navigation reason.
+ */
+interface ContentMetadata {
+    /**
+     * Date and Time at which the Content was created.
+     */
+    createdAt: string;
+    /**
+     * Combination of SLUG and Parent SLUG of the Content
+     */
+    fullSlug: string;
+    /**
+     * Unique identifier for the object.
+     */
+    id: string;
+    /**
+     * Define the type of Content, whether it is a FOLDER or DOCUMENT.
+     */
+    kind: 'FOLDER' | 'DOCUMENT';
+    /**
+     * Name of the Content
+     */
+    name: string;
+    /**
+     * Parent SLUG of the Content
+     */
+    parentSlug: string;
+    /**
+     * Date and Time at which the Content was published.
+     */
+    publishedAt?: string;
+    /**
+     * SLUG of the Content
+     */
+    slug: string;
+    /**
+     * Date and Time at which the Content was updated.
+     */
+    updatedAt: string;
+}
+
+/**
+ * Key-Value Object. Where Key is a Unique identifier for the Content object and Value is Content Metadata.
+ */
+interface Links {
+    [key: string]: ContentMetadata;
+}
+
+/**
+ * Key-Value Object. Where Key is a Unique identifier for the Content object and Value is Content.
+ */
+interface References {
+    [key: string]: Content;
+}
+
+/**
+ * Content defines a shared object for all possible Content Types.
+ */
+interface Content<T extends ContentData = ContentData> extends ContentMetadata {
+    /**
+     * Content Data
+     */
+    data?: T;
+    /**
+     * All links used in the content.
+     */
+    links?: Links;
+    /**
+     * All references used in the content.
+     */
+    references?: References;
+}
+
+interface Locale {
+    /**
+     * Unique identifier for the Locale.
+     */
+    id: string;
+    /**
+     * Name of the Locale.
+     */
+    name: string;
+}
+
+/**
+ * Key-Value Object. Where Key is Translation ID and Value is Translated Content
+ */
+interface Translations {
+    [key: string]: string;
+}
+
+type LocalessClientOptions = {
+    /**
+     * A fully qualified domain name with protocol (http/https) and port.
+     *
+     * Example: https://my-localess.web.app
+     */
+    origin: string;
+    /**
+     * Localess space ID can be found in the Localess Space settings
+     */
+    spaceId: string;
+    /**
+     * Localess API token can be found in the Localess Space settings
+     */
+    token: string;
+    /**
+     * Content version to fetch, leave empty for 'published' or 'draft' for the latest draft
+     */
+    version?: 'draft' | string;
+    /**
+     * Enable debug mode
+     */
+    debug?: boolean;
+    /**
+     * Cache TTL (time to live) for API responses. Default is 5 minutes (300000 ms).
+     * Set to false to disable caching.
+     */
+    cacheTTL?: number | false;
+};
+type LinksFetchParams = {
+    /**
+     * Content Kind. FOLDER or DOCUMENT. If not provided, it will return all.
+     * @example 'DOCUMENT'
+     */
+    kind?: 'DOCUMENT' | 'FOLDER';
+    /**
+     * Content parent slug.
+     * @example 'legal/policy'
+     */
+    parentSlug?: string;
+    /**
+     * If **true**, exclude all sub slugs, otherwise include all content under current selected **parent slug**.
+     * @example false
+     */
+    excludeChildren?: boolean;
+};
+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;
+    /**
+     * Locale identifier (ISO 639-1) to fetch content in, leave empty for default locale.
+     *
+     * Example: en
+     */
+    locale?: string;
+    /**
+     * Resolve references in the content data. Default is false.
+     */
+    resolveReference?: boolean;
+    /**
+     * Resolve links in the content data. Default is false.
+     */
+    resolveLink?: boolean;
+};
+interface LocalessClient {
+    /**
+     * Get all links
+     * @param params{LinksFetchParams} - Fetch parameters
+     * @returns {Promise<Links>}
+     */
+    getLinks(params?: LinksFetchParams): Promise<Links>;
+    /**
+     * Get content by SLUG
+     * @param slug{string} - Content SLUG
+     * @param params{ContentFetchParams} - Fetch parameters
+     * @returns {Promise<Content>}
+     */
+    getContentBySlug<T extends ContentData = ContentData>(slug: string, params?: ContentFetchParams): Promise<Content<T>>;
+    /**
+     * Get content by ID
+     * @param id{string} - Content ID
+     * @param params{ContentFetchParams} - Fetch parameters
+     * @returns {Promise<Content>}
+     */
+    getContentById<T extends ContentData = ContentData>(id: string, params?: ContentFetchParams): Promise<Content<T>>;
+    /**
+     * Get translations for the given locale
+     * @param locale{string} - Locale identifier (ISO 639-1)
+     */
+    getTranslations(locale: string): Promise<Translations>;
+    syncScriptUrl(): string;
+    assetLink(asset: ContentAsset | string): string;
+}
+/**
+ * Create a Localess API Client
+ * @param {LocalessClientOptions} options connection details
+ */
+declare function localessClient(options: LocalessClientOptions): LocalessClient;
+
+/**
+ * Adds Localess editable attributes to a content item.
+ * @param content
+ * @returns An object containing data-ll-id and data-ll-schema attributes.
+ */
+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.
+ * @param fieldName
+ * @returns An object containing data-ll-field attribute.
+ */
+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
+ * @param {string} origin A fully qualified domain name with protocol (http/https) and port.
+ * @param {boolean} force Force Script Injection even if the application is not in Visual Editor.
+ */
+declare function loadLocalessSync(origin: string, force?: boolean): void;
+
+declare const isBrowser: () => boolean;
+declare const isServer: () => boolean;
+declare const isIframe: () => boolean;
+
+type EventToAppType = 'save' | 'publish' | 'pong' | 'input' | 'change' | 'enterSchema' | 'hoverSchema';
+type EventCallback = (event: EventToApp) => void;
+type EventToApp = {
+    type: 'save' | 'publish' | 'pong';
+} | {
+    type: 'input' | 'change';
+    data: any;
+} | {
+    type: 'enterSchema' | 'hoverSchema';
+    id: string;
+    schema: string;
+    field?: string;
+};
+interface LocalessSync {
+    onChange: (callback: EventCallback) => void;
+    on: (event: EventToAppType | EventToAppType[], callback: EventCallback) => void;
+}
+declare global {
+    interface Window {
+        localess?: LocalessSync;
+    }
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,305 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  isBrowser: () => isBrowser,
+  isIframe: () => isIframe,
+  isServer: () => isServer,
+  llEditable: () => llEditable,
+  llEditableField: () => llEditableField,
+  loadLocalessSync: () => loadLocalessSync,
+  localessClient: () => localessClient,
+  localessEditable: () => localessEditable,
+  localessEditableField: () => localessEditableField
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils.ts
+var RESET = "\x1B[0m";
+var FG_BLUE = "\x1B[34m";
+var isBrowser = () => typeof window !== "undefined";
+var isServer = () => typeof window === "undefined";
+var isIframe = () => isBrowser() && window.self !== window.top;
+
+// src/cache.ts
+var NoCache = class {
+  set(key, value) {
+  }
+  get(key) {
+    return void 0;
+  }
+  has(key) {
+    return false;
+  }
+};
+var TTLCache = class {
+  /**
+   * Creates a TTLCache with a specified time-to-live (TTL) for each entry.
+   * default is 5 minutes (300000 ms).
+   * @param ttlMs
+   */
+  constructor(ttlMs = 3e5) {
+    this.ttlMs = ttlMs;
+  }
+  cache = /* @__PURE__ */ new Map();
+  set(key, value) {
+    this.cache.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  has(key) {
+    return this.get(key) !== void 0;
+  }
+};
+
+// src/client.ts
+var LOG_GROUP = `${FG_BLUE}[Localess:Client]${RESET}`;
+function localessClient(options) {
+  if (options.debug) {
+    console.log(LOG_GROUP, "Client Options : ", options);
+  }
+  const fetchOptions = {
+    redirect: "follow",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      "X-Localess-Agent": "Localess-JS-Client",
+      "X-Localess-Agent-Version": "0.9.0"
+    }
+  };
+  const cache = options.cacheTTL === false ? new NoCache() : new TTLCache(options.cacheTTL);
+  return {
+    async getLinks(params) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getLinks() params : ", JSON.stringify(params));
+      }
+      let kind = "";
+      if (params?.kind) {
+        kind = `&kind=${params.kind}`;
+      }
+      let parentSlug = "";
+      if (params?.parentSlug) {
+        parentSlug = `&parentSlug=${params.parentSlug}`;
+      }
+      let excludeChildren = "";
+      if (params?.excludeChildren) {
+        excludeChildren = `&excludeChildren=${params.excludeChildren}`;
+      }
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/links?token=${options.token}${kind}${parentSlug}${excludeChildren}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getLinks fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getLinks cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getLinks status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getLinks error : ", error);
+        return {};
+      }
+    },
+    async getContentBySlug(slug, params) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentBySlug() slug : ", slug);
+        console.log(LOG_GROUP, "getContentBySlug() params : ", JSON.stringify(params));
+      }
+      let version = "";
+      if (options?.version && options.version == "draft") {
+        version = `&version=${options.version}`;
+      }
+      if (params?.version && params.version == "draft") {
+        version = `&version=${params.version}`;
+      }
+      const locale = params?.locale ? `&locale=${params.locale}` : "";
+      const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
+      const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/slugs/${slug}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentBySlug fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentBySlug cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentBySlug status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getContentBySlug error : ", error);
+        return {};
+      }
+    },
+    async getContentById(id, params) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentById() id : ", id);
+        console.log(LOG_GROUP, "getContentById() params : ", JSON.stringify(params));
+      }
+      let version = "";
+      if (options?.version && options.version == "draft") {
+        version = `&version=${options.version}`;
+      }
+      if (params?.version && params.version == "draft") {
+        version = `&version=${params.version}`;
+      }
+      const locale = params?.locale ? `&locale=${params.locale}` : "";
+      const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
+      const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/${id}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentById fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentById cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentById status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getContentById error : ", error);
+        return {};
+      }
+    },
+    async getTranslations(locale) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getTranslations() locale : ", locale);
+      }
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/translations/${locale}?token=${options.token}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getTranslations fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getTranslations cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getTranslations status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getTranslations error : ", error);
+        return {};
+      }
+    },
+    syncScriptUrl() {
+      return `${options.origin}/scripts/sync-v1.js`;
+    },
+    assetLink(asset) {
+      if (typeof asset === "string") {
+        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset}`;
+      } else {
+        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset.uri}`;
+      }
+    }
+  };
+}
+
+// src/editable.ts
+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
+  };
+}
+function localessEditableField(fieldName) {
+  return {
+    "data-ll-field": fieldName
+  };
+}
+function llEditableField(fieldName) {
+  return {
+    "data-ll-field": fieldName
+  };
+}
+
+// src/sync.ts
+var JS_SYNC_ID = "localess-js-sync";
+function loadLocalessSync(origin, force = false) {
+  if (isServer()) return;
+  if (!isIframe()) return;
+  const isSyncLoaded = typeof window.localess !== "undefined";
+  if (isSyncLoaded) return;
+  const scriptEl = document.getElementById(JS_SYNC_ID);
+  if (scriptEl) return;
+  const script = document.createElement("script");
+  script.id = JS_SYNC_ID;
+  script.type = "text/javascript";
+  script.src = `${origin}/scripts/sync-v1.js`;
+  script.async = true;
+  script.onerror = (error) => console.error(error);
+  script.onload = (event) => console.info("Localess Sync Script loaded");
+  document.head.appendChild(script);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isBrowser,
+  isIframe,
+  isServer,
+  llEditable,
+  llEditableField,
+  loadLocalessSync,
+  localessClient,
+  localessEditable,
+  localessEditableField
+});

package/dist/index.mjs

@@ -0,0 +1,270 @@
+// src/utils.ts
+var RESET = "\x1B[0m";
+var FG_BLUE = "\x1B[34m";
+var isBrowser = () => typeof window !== "undefined";
+var isServer = () => typeof window === "undefined";
+var isIframe = () => isBrowser() && window.self !== window.top;
+
+// src/cache.ts
+var NoCache = class {
+  set(key, value) {
+  }
+  get(key) {
+    return void 0;
+  }
+  has(key) {
+    return false;
+  }
+};
+var TTLCache = class {
+  /**
+   * Creates a TTLCache with a specified time-to-live (TTL) for each entry.
+   * default is 5 minutes (300000 ms).
+   * @param ttlMs
+   */
+  constructor(ttlMs = 3e5) {
+    this.ttlMs = ttlMs;
+  }
+  cache = /* @__PURE__ */ new Map();
+  set(key, value) {
+    this.cache.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  has(key) {
+    return this.get(key) !== void 0;
+  }
+};
+
+// src/client.ts
+var LOG_GROUP = `${FG_BLUE}[Localess:Client]${RESET}`;
+function localessClient(options) {
+  if (options.debug) {
+    console.log(LOG_GROUP, "Client Options : ", options);
+  }
+  const fetchOptions = {
+    redirect: "follow",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      "X-Localess-Agent": "Localess-JS-Client",
+      "X-Localess-Agent-Version": "0.9.0"
+    }
+  };
+  const cache = options.cacheTTL === false ? new NoCache() : new TTLCache(options.cacheTTL);
+  return {
+    async getLinks(params) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getLinks() params : ", JSON.stringify(params));
+      }
+      let kind = "";
+      if (params?.kind) {
+        kind = `&kind=${params.kind}`;
+      }
+      let parentSlug = "";
+      if (params?.parentSlug) {
+        parentSlug = `&parentSlug=${params.parentSlug}`;
+      }
+      let excludeChildren = "";
+      if (params?.excludeChildren) {
+        excludeChildren = `&excludeChildren=${params.excludeChildren}`;
+      }
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/links?token=${options.token}${kind}${parentSlug}${excludeChildren}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getLinks fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getLinks cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getLinks status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getLinks error : ", error);
+        return {};
+      }
+    },
+    async getContentBySlug(slug, params) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentBySlug() slug : ", slug);
+        console.log(LOG_GROUP, "getContentBySlug() params : ", JSON.stringify(params));
+      }
+      let version = "";
+      if (options?.version && options.version == "draft") {
+        version = `&version=${options.version}`;
+      }
+      if (params?.version && params.version == "draft") {
+        version = `&version=${params.version}`;
+      }
+      const locale = params?.locale ? `&locale=${params.locale}` : "";
+      const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
+      const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/slugs/${slug}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentBySlug fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentBySlug cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentBySlug status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getContentBySlug error : ", error);
+        return {};
+      }
+    },
+    async getContentById(id, params) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentById() id : ", id);
+        console.log(LOG_GROUP, "getContentById() params : ", JSON.stringify(params));
+      }
+      let version = "";
+      if (options?.version && options.version == "draft") {
+        version = `&version=${options.version}`;
+      }
+      if (params?.version && params.version == "draft") {
+        version = `&version=${params.version}`;
+      }
+      const locale = params?.locale ? `&locale=${params.locale}` : "";
+      const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
+      const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/${id}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getContentById fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentById cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getContentById status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getContentById error : ", error);
+        return {};
+      }
+    },
+    async getTranslations(locale) {
+      if (options.debug) {
+        console.log(LOG_GROUP, "getTranslations() locale : ", locale);
+      }
+      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/translations/${locale}?token=${options.token}`;
+      if (options.debug) {
+        console.log(LOG_GROUP, "getTranslations fetch url : ", url);
+      }
+      if (cache.has(url)) {
+        if (options.debug) {
+          console.log(LOG_GROUP, "getTranslations cache hit");
+        }
+        return cache.get(url);
+      }
+      try {
+        const response = await fetch(url, fetchOptions);
+        if (options.debug) {
+          console.log(LOG_GROUP, "getTranslations status : ", response.status);
+        }
+        const data = await response.json();
+        cache.set(url, data);
+        return data;
+      } catch (error) {
+        console.error(LOG_GROUP, "getTranslations error : ", error);
+        return {};
+      }
+    },
+    syncScriptUrl() {
+      return `${options.origin}/scripts/sync-v1.js`;
+    },
+    assetLink(asset) {
+      if (typeof asset === "string") {
+        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset}`;
+      } else {
+        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset.uri}`;
+      }
+    }
+  };
+}
+
+// src/editable.ts
+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
+  };
+}
+function localessEditableField(fieldName) {
+  return {
+    "data-ll-field": fieldName
+  };
+}
+function llEditableField(fieldName) {
+  return {
+    "data-ll-field": fieldName
+  };
+}
+
+// src/sync.ts
+var JS_SYNC_ID = "localess-js-sync";
+function loadLocalessSync(origin, force = false) {
+  if (isServer()) return;
+  if (!isIframe()) return;
+  const isSyncLoaded = typeof window.localess !== "undefined";
+  if (isSyncLoaded) return;
+  const scriptEl = document.getElementById(JS_SYNC_ID);
+  if (scriptEl) return;
+  const script = document.createElement("script");
+  script.id = JS_SYNC_ID;
+  script.type = "text/javascript";
+  script.src = `${origin}/scripts/sync-v1.js`;
+  script.async = true;
+  script.onerror = (error) => console.error(error);
+  script.onload = (event) => console.info("Localess Sync Script loaded");
+  document.head.appendChild(script);
+}
+export {
+  isBrowser,
+  isIframe,
+  isServer,
+  llEditable,
+  llEditableField,
+  loadLocalessSync,
+  localessClient,
+  localessEditable,
+  localessEditableField
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@localess/client",
+  "version": "0.9.2-dev.20260216094809",
+  "description": "Universal JavaScript/TypeScript SDK for Localess's API.",
+  "keywords": [
+    "localess",
+    "sdk",
+    "api",
+    "client",
+    "javascript",
+    "typescript"
+  ],
+  "author": "Lessify",
+  "homepage": "https://github.com/Lessify/localess-js",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lessify/localess-js.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/Lessify/localess-js/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "openapi3-ts": "^4.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">= 20.0.0"
+  }
+}