Skip to content

k.history ​

Query site edit history, compare versions, perform rollbacks, and inspect remote site logs

Execution ContextPrerequisitesTypical Use
Api, CodeBlock, <script env="server">Authenticated org-matching user for local methods (except videoLog(versionId))Audit CMS edits, inspect diffs, undo/restore changes, or query remote logs

Authentication and Organization Requirement

Except for the single-argument local videoLog(versionId), every local k.history method requires an authenticated Kooboo platform user (k.account) whose current organization matches the site's organization, or it throws "An authenticated user is required".

Quick Start ​

js
k.api.get("history-recent", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const page = k.history.list(10)
    return {
        totalCount: page.totalCount,
        items: page.list
    }
})

Quick Reference ​

Method / PropertyDescriptionReturns
k.history.list(top) / list(query)Fetch recent site edit logs (pass numeric top in scripts)SiteLogPage
k.history.get(logId)Get a single local CMS edit log entry by log IDSiteLogItem
k.history.versions(logId) / (nameOrId, storeName?, tableName?)List all recorded historical versions of an objectSiteLogVersion[]
k.history.compare(id) / compare(id1, id2)Diff a version against latest or compare two historical versionsVersionCompareViewModel
k.history.videoLog(versionId)Read recorded editor replay video JSON for a versionstring | null
k.history.undo(logId)Revert a single local CMS change and log the rollbackboolean
k.history.undoMany(logIds)Revert multiple local CMS changes in a batch (max 1,000)boolean
k.history.restoreTo(logId) / restoreTo(time)Restore the entire site state to an earlier log ID or datenumber
k.history.checkOut(options)Provision a new org website from a historical snapshotSiteCheckoutResult
k.history.lastLog(pageIndex, pagesize, siteUrl)Fetch paginated edit logs from a remote Kooboo siteRemoteLastLogResult
k.history.versions(keyHash, storeHash, tableHash, siteUrl)List historical versions of an object on a remote siteItemVersionViewModel[]
k.history.compare(id1, id2, siteUrl)Compare two versions on a remote Kooboo siteVersionCompareViewModel
k.history.videoLog(versionId, siteUrl)Fetch replay video JSON for a version on a remote sitestring

Overview ​

k.history provides server-side script access to CMS edit logs and version history for the current website, including log pagination, object version inspection, text/image diffs, edit replay video data, change rollback, checking out a historical snapshot into a new site, and querying remote Kooboo sites. k.site.editLog exposes the exact same API surface and behavior as k.history.

CategoryMethodsPurpose
Read-only Historylist, get, versions, compare, videoLogInspect local edit logs, object versions, content/image diffs, and replay data
Destructive Rollback & Checkoutundo, undoMany, restoreTo, checkOutRevert site changes, restore the site to an earlier state, or fork a historical snapshot into a new site
Remote Site Diff & VideoLoglastLog, versions (4 args), compare (3 args), videoLog (2 args)Query and compare edit logs, versions, and replay videos on another siteUrl

Read-only History ​

list() ​

Lists recent CMS edit logs for the current site, declaring two overloads:

  1. Numeric limit: k.history.list(top) returns the latest top log entries (pageNr is 1; values <= 0 default to 50, clamped to a maximum of 200).
  2. Structured query: k.history.list(query) corresponds to the SiteLogQuery overload in type definitions.

Runtime Overload Resolution Note

At runtime, passing a plain JavaScript object literal (such as { pageNr: 1, pageSize: 5, storeName: "Code" }) to k.history.list(...) matches the numeric list(top) overload first with top = 0, returning the latest 50 unfiltered entries (pageSize: 50) without applying SiteLogQuery filters. In site scripts, pass a numeric top argument (1–200) to k.history.list(top) and filter page.list in JavaScript when needed.

Parameters (list(top)):

ParameterTypeRequiredDefaultDescription
topnumberyes-Number of most recent logs to return (<= 0 falls back to 50; max 200)

Returns: SiteLogPage.

js
k.api.get("history-recent", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const page = k.history.list(10)
    const codeLogs = page.list.filter((item) => item.storeName === "Code")

    return {
        totalCount: page.totalCount,
        pageSize: page.pageSize,
        totalPages: page.totalPages,
        recentItems: page.list,
        recentCodeLogs: codeLogs
    }
})

get() ​

Gets a single local CMS edit log entry by its numeric log ID.

Parameters:

ParameterTypeRequiredDescription
logIdnumberyesPositive log ID; throws if non-positive or not found

Returns: SiteLogItem.

js
k.api.get("history-detail", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const recent = k.history.list(1)
    if (recent.list.length === 0) {
        return { item: null }
    }

    const detail = k.history.get(recent.list[0].id)
    return { detail: detail }
})

versions() ​

Lists all recorded historical versions of an object (newest first), supporting two local overloads:

  1. By log ID: k.history.versions(logId) looks up every recorded version of the object referenced by logId.
  2. By object identifier: k.history.versions(nameOrId, storeName, tableName) looks up versions by object name or GUID. Provide either storeName (such as "Page", "View", "Layout", "Code", "HtmlBlock", "Label") or tableName (dynamic database table name), never both and never neither.

Querying Deleted Objects

If a CMS object whose ID is not derived from its name (such as a Page, View, or Code item) has been deleted, looking it up by name throws a not-found error. Pass its GUID string as nameOrId instead.

Parameters:

ParameterTypeRequiredDescription
logIdnumberyes (overload 1)Any log ID belonging to the target object
nameOrIdstringyes (overload 2)Object name or GUID string
storeNamestringno (mutually exclusive with tableName)CMS store name (for example "Code", "Page")
tableNamestringno (mutually exclusive with storeName)Dynamic table name

Returns: SiteLogVersion[].

js
k.api.get("history-versions", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const recent = k.history.list(10)
    const target = recent.list.find((item) => item.storeName !== "Table" && item.itemName)
    if (!target) {
        return { versions: [] }
    }

    const byLogId = k.history.versions(target.id)
    const byName = k.history.versions(target.itemName, target.storeName)

    return {
        itemName: target.itemName,
        storeName: target.storeName,
        byLogId: byLogId,
        sameCount: byLogId.length === byName.length
    }
})

compare() ​

Compares two versions of the same object:

  1. Against latest: k.history.compare(id) compares version id against the latest recorded log of the same object.
  2. Two specific versions: k.history.compare(id1, id2) compares two specific versions of the same object. If id1 > id2, the server automatically swaps them so the older version is on the left (id1 / title1 / source1) and the newer version is on the right (id2 / title2 / source2).

Runtime Value of dataType

While TypeScript IntelliSense types dataType as 'String' | 'Image', serialized JSON responses return the underlying numeric enum at runtime: 0 for String and 1 for Image.

Parameters:

ParameterTypeRequiredDescription
id / id1numberyesFirst positive log version ID
id2numbernoSecond positive log version ID (omit to compare against the latest version)

Returns: VersionCompareViewModel.

js
k.api.get("history-compare", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const recent = k.history.list(50)
    for (const item of recent.list) {
        if (item.storeName === "Table") continue
        const versions = k.history.versions(item.id)
        if (versions.length >= 2) {
            return {
                withLatest: k.history.compare(versions[versions.length - 1].id),
                twoVersions: k.history.compare(versions[1].id, versions[0].id)
            }
        }
    }

    return { message: "No object with multiple versions found" }
})

videoLog() ​

Reads the recorded editor replay video JSON for a local version ID, returning null if no video exists for that version.

Parameters:

ParameterTypeRequiredDescription
versionIdnumberyesVersion log ID

Returns: string | null.

js
k.api.get("history-video", () => {
    const versionId = Number(k.request.queryString.get("versionId") || 0)
    if (!versionId) {
        return { video: null }
    }

    const video = k.history.videoLog(versionId)
    return {
        hasVideo: typeof video === "string" && video.length > 0,
        video: video
    }
})

Destructive Rollback & Checkout ​

Data Modification and Site Provisioning Warning

These methods mutate live website content, overwrite multiple objects, or provision brand-new websites in your organization, and rollbacks append new edit logs:

  • Call them only after authenticating an authorized organization user and confirming the exact target logId;
  • undoMany() validates all IDs before making changes and accepts at most 1,000 log IDs per call;
  • restoreTo() and checkOut() fail if more than 99,999 subsequent logs exist after the target point;
  • Never expose rollback or checkout endpoints without strict authentication and confirmation checks.

undo() ​

Reverts a single local CMS change and records a new edit log for the rollback.

Parameters:

ParameterTypeRequiredDescription
logIdnumberyesPositive log ID to undo (throws if non-positive or not found)

Returns: boolean (true on success).

undoMany() ​

Reverts multiple local CMS changes in a batch. All log IDs are validated and deduplicated before any state is modified.

Parameters:

ParameterTypeRequiredDescription
logIdsnumber[]yesNon-empty array of positive log IDs (maximum 1,000 items)

Returns: boolean (true on success).

restoreTo() ​

Restores the entire local website to an earlier log ID or UTC Date cutoff in history, generating new edit logs for the restoration.

Parameters:

ParameterTypeRequiredDescription
logIdnumberyes (overload 1)Target log ID (at most 99,999 later logs allowed)
timeDateyes (overload 2)Target cutoff date/time (restores to the latest log at or before time; throws if none exists)

Returns: number (the restored target log ID).

checkOut() ​

Creates another website within the current organization containing the local site's state at a historical log ID. If checkout fails mid-way, the newly created site is cleaned up automatically.

Parameters:

ParameterTypeRequiredDescription
optionsSiteCheckoutOptionsyesCheckout options object
options.logIdnumberyesTarget historical log ID (at most 99,999 later logs allowed)
options.siteNamestringyesNew site name (must be available in the organization)
options.fullDomainstringyesFull domain binding for the new site (must not already be in use)
options.publishedbooleanyesWhether to mark the checked-out site as published

Returns: SiteCheckoutResult.

Remote Site Diff & VideoLog ​

These four methods query remote Kooboo site log endpoints over HTTP and automatically forward the current request's Cookie and Authorization headers (see TypeScript Definitions below for exact parameter and return types):

  • k.history.lastLog(pageIndex, pagesize, siteUrl)
  • k.history.versions(keyHash, storeNameHash, tableNameHash, siteUrl)
  • k.history.compare(id1, id2, siteUrl)
  • k.history.videoLog(versionId, siteUrl)

Trailing Slash in siteUrl

Pass siteUrl without a trailing slash (for example "https://example.com" or k.site.info.baseUrl.replace(/\/+$/, "")). Passing a URL ending in / produces a double-slash endpoint path (//_api/...) and yields null fields.

Parameters:

MethodParametersDescription
lastLog(pageIndex, pagesize, siteUrl)pageIndex: number, pagesize: number, siteUrl: stringFetch paginated edit logs from a remote Kooboo site
versions(keyHash, storeNameHash, tableNameHash, siteUrl)keyHash: string, storeNameHash: number, tableNameHash: number, siteUrl: stringList remote object versions using hashes from lastLog entries
compare(id1, id2, siteUrl)id1: number, id2: number, siteUrl: stringCompare two versions on a remote site
videoLog(versionId, siteUrl)versionId: number, siteUrl: stringFetch edit-replay video JSON for a remote version ID

Example:

js
k.api.get("history-remote", () => {
    const siteUrl = k.site.info.baseUrl.replace(/\/+$/, "")
    const remotePage = k.history.lastLog(1, 5, siteUrl)
    const first = remotePage.list.length > 0 ? remotePage.list[0] : null
    if (!first) {
        return { totalCount: remotePage.totalCount, items: [] }
    }

    const remoteVersions = k.history.versions(
        String(first.keyHash),
        first.storeNameHash,
        first.tableNameHash,
        siteUrl
    )
    const diff = remoteVersions.length >= 2
        ? k.history.compare(remoteVersions[1].id, remoteVersions[0].id, siteUrl)
        : null
    const video = k.history.videoLog(first.id, siteUrl)

    return {
        totalCount: remotePage.totalCount,
        firstId: first.id,
        versionsCount: remoteVersions.length,
        hasVideo: typeof video === "string" && video.length > 0,
        diff: diff
    }
})

TypeScript Definitions ​

Show full TypeScript definitions
ts
interface KEditLog {
  // Read-only History
  list(top: number): SiteLogPage;
  list(query: SiteLogQuery): SiteLogPage;
  get(logId: number): SiteLogItem;
  versions(logId: number): SiteLogVersion[];
  versions(nameOrId: string, storeName?: string, tableName?: string): SiteLogVersion[];
  compare(id: number): VersionCompareViewModel;
  compare(id1: number, id2: number): VersionCompareViewModel;
  videoLog(versionId: number): string;

  // Destructive Rollback & Checkout
  undo(logId: number): boolean;
  undoMany(logIds: number[]): boolean;
  restoreTo(logId: number): number;
  restoreTo(time: Date): number;
  checkOut(options: SiteCheckoutOptions): SiteCheckoutResult;

  // Remote Site Diff & VideoLog
  lastLog(pageIndex: number, pagesize: number, siteUrl: string): RemoteLastLogResult;
  videoLog(versionId: number, siteUrl: string): string;
  versions(keyHash: string, storeNameHash: number, tableNameHash: number, siteUrl: string): ItemVersionViewModel[];
  compare(id1: number, id2: number, siteUrl: string): VersionCompareViewModel;
}

interface SiteLogPage {
  list: SiteLogItem[];
  totalCount: number;
  pageNr: number;
  pageSize: number;
  totalPages: number;
}

interface SiteLogQuery {
  pageNr: number;
  pageSize: number;
  actionType: string; // "Add" | "Update" | "Delete"
  storeName: string;
  tableName: string;
  name: string;
  userId?: any;
  startDate?: Date;
  endDate?: Date;
}

interface SiteLogItem {
  id: number;
  lastModified: Date;
  timeTick: number;
  userId: any;
  userName: string;
  itemName: string;
  storeName: string;
  keyHash: any;
  storeNameHash: number;
  tableNameHash: number;
  tableName: string;
  actionType: string;
  isAI: boolean;
  hasVideo: boolean;
}

interface SiteLogVersion {
  id: number;
  lastModified: Date;
  userId: any;
  userName: string;
  actionType: string;
  isAI: boolean;
  hasVideo: boolean;
}

type VersionDataType = "String" | "Image";

interface VersionCompareViewModel {
  title1: string;
  title2: string;
  objectId: any;
  constType: number;
  id1: number;
  id2: number;
  source1: string;
  source2: string;
  dataType: VersionDataType;
}

interface SiteCheckoutOptions {
  logId: number;
  siteName: string;
  fullDomain: string;
  published: boolean;
}

interface SiteCheckoutResult {
  siteId: any;
  siteName: string;
  fullDomain: string;
  published: boolean;
}

interface RemoteLastLogResult {
  list: SiteLogViewModel[];
  totalCount: number;
  pageNr: number;
  pageSize: number;
  totalPages: number;
}

interface SiteLogViewModel {
  id: number;
  lastModified: Date;
  userName: string;
  itemName: string;
  storeName: string;
  keyHash: any;
  storeNameHash: number;
  tableNameHash: number;
  tableName: string;
  actionType: string;
  hasVideo: boolean;
}

interface ItemVersionViewModel {
  id: number;
  lastModified: Date;
  userName: string;
  hasVideo: boolean;
}
  • k.site — Versioned structured site resources (k.site.editLog points to the same interface as k.history)
  • k.account.login — Platform user login and session authentication
  • Site Logs (Admin) — Admin UI for version history, diffs, and video replay