@libretexts/cxone-expert-node 1.0.0

package/.github/workflows/release.yaml

@@ -0,0 +1,37 @@
+name: Release New Version
+
+on: workflow_dispatch
+
+jobs:
+  check_authorization:
+    name: Check authorization to release new version
+    runs-on: ubuntu-latest
+    outputs:
+      isAuthorized: ${{ steps.check-auth.outputs.is_authorized }}
+    steps:
+      - name: check-auth
+        id: check-auth
+        run: echo "is_authorized=${{ contains(secrets.DEPLOYMENT_AUTHORIZED_USERS, github.triggering_actor) }}" >> $GITHUB_OUTPUT
+  release:
+    name: Release new semantic version
+    needs: check_authorization
+    if: needs.check_authorization.outputs.isAuthorized == 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      didRelease: ${{ steps.semver.outputs.new_release_published }}
+      newVersion: ${{ steps.semver.outputs.new_release_version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: semantic-release
+        uses: cycjimmy/semantic-release-action@v3
+        id: semver
+        env:
+          GITHUB_TOKEN: ${{ secrets.LIBREBOT_ACCESS_TOKEN }}
+          GIT_AUTHOR_NAME: libretexts-bot
+          GIT_AUTHOR_EMAIL: dev@libretexts.org
+          GIT_COMMITTER_NAME: libretexts-bot
+          GIT_COMMITTER_EMAIL: dev@libretexts.org

package/.releaserc.json

@@ -0,0 +1,15 @@
+{
+    "branches": ["main"],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      ["@semantic-release/npm", {
+        "npmPublish": false
+      }],
+      ["@semantic-release/git", {
+        "assets": ["package.json"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]"
+      }],
+      "@semantic-release/github"
+    ]
+  }

package/README.md

@@ -0,0 +1,40 @@
+# CXone Expert Node SDK
+This package is a custom SDK developed by [LibreTexts](https://libretexts.org) to interact with the [CXone Expert API](https://expert-help.nice.com/Integrations_and_Extending_Content/API). It should be noted that this package is NOT developed or maintained by CXone and, as such, does not guarantee 100% compatibility with the latest API updates.
+
+## Install
+
+```
+npm install @libretexts/cxone-expert-node
+```
+
+## Usage
+```
+import Expert from "@libretexts/cxone-expert-node";
+
+const tld = "mysite.example.com"; // Your CXone site domain
+
+const expert = new Expert(tld);
+
+// Authenticate using server credentials
+const authInstance = await expert.auth.ServerToken({
+  key: "mykey",
+  secret: "mysecret",
+  user: "myuser",
+});
+
+// Or, use auth.BrowserToken() to use a CXone provided JWT (not intended for production use)
+
+// Get authentication header(s) (X-Deki-Token)
+const authHeaders = authInstance.getHeader();
+
+// Use the appropriate module(s) to interact with your site's API
+const page = await expert.pages.getPage(123, {
+  auth: authHeaders,
+  tld,
+});
+
+console.log(page);
+```
+
+## License
+This package is open-source and free to use under the [MIT License](http://opensource.org/licenses/MIT).

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 LibreTexts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@libretexts/cxone-expert-node",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.ts",
+  "scripts": {
+    "dev": "tsx test.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "LibreTexts, Inc.",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.2.0",
+    "dotenv": "^16.4.5",
+    "tsx": "^4.17.0",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "axios": "^1.7.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import pages from './modules/pages';
+import auth from './modules/auth';
+import requests from './modules/requests';
+import { AuthObject, BaseArgs, BrowserTokenParams, ExpertGlobalOptions, ServerTokenParams } from './types';
+import Pages from './modules/pages';
+
+
+export default class Expert {
+    private globals: ExpertGlobalOptions = {};
+    private _pages?: Pages;
+    private _auth?: auth;
+
+    constructor(tld?: string) {
+        if (tld) {
+            this.globals.tld = tld;
+        }
+    }
+
+    public get pages(): Pages {
+        if (!this._pages) {
+            this._pages = new pages(this.globals);
+        }
+
+        return this._pages;
+    }
+
+    public get auth(): auth {
+        if (!this._auth) {
+            this._auth = new auth();
+        }
+
+        return this._auth;
+    }
+
+}

package/src/modules/auth.ts

@@ -0,0 +1,31 @@
+import { AuthObject, BrowserTokenParams, ServerTokenParams } from "../types";
+import { createHmac } from 'crypto';
+
+export default class Auth {
+    private token: string | null = null;
+
+    public BrowserToken({ key }: BrowserTokenParams) {
+        this.token = key;
+        return this;
+    }
+
+    public ServerToken({ key, secret, user }: ServerTokenParams) {
+        const hmac = createHmac('sha256', secret);
+        const epoch = Math.floor(Date.now() / 1000);
+        hmac.update(`${key}_${epoch}_${user}`);
+        const hash = hmac.digest('hex');
+        this.token = `tkn_${key}_${epoch}_${user}_${hash}`;
+        return this;
+    }
+
+    public getToken() {
+        return this.token;
+    }
+
+    public getHeader(): AuthObject {
+        return {
+            'X-Deki-Token': this.token
+        }
+    }
+}
+

package/src/modules/pages.ts

@@ -0,0 +1,73 @@
+import { BaseArgs, ExpertGlobalOptions, GetPageContentsParams, GetPageContentsResponse, GetPageParams, GetPageResponse, GetPageSecurityParams, GetPageSecurityResponse, GetPageSubPagesParams, GetPageSubPagesResponse } from "../types";
+import { getTld } from "../utils";
+import Auth from "./auth";
+import Requests from "./requests";
+
+export default class Pages {
+    private globals: ExpertGlobalOptions;
+    private _auth?: Auth;
+
+    constructor(args: ExpertGlobalOptions, auth?: Auth) {
+        this.globals = args;
+        this._auth = auth;
+    }
+
+    private parsePageId(id: string | number) {
+        if (typeof id === 'number') {
+            return id.toString();
+        }
+        return `=${encodeURIComponent(id)}`;
+    }
+
+    public async getPage(id: string | number, funcArgs: BaseArgs, reqArgs?: GetPageParams) {
+        const pageId = this.parsePageId(id);
+        const tld = getTld(this.globals, funcArgs.tld);
+        const requests = new Requests(tld, funcArgs.auth);
+
+        const res = await requests.get<GetPageResponse>(`/pages/${pageId}`, {
+            params: {
+                ...reqArgs
+            }
+        });
+        return res.data
+    }
+
+    public async getPageContents(id: string | number, funcArgs: BaseArgs, reqArgs?: GetPageContentsParams) {
+        const pageId = this.parsePageId(id);
+        const tld = getTld(this.globals, funcArgs.tld);
+        const requests = new Requests(tld, funcArgs.auth);
+
+        const res = await requests.get<GetPageContentsResponse>(`/pages/${pageId}/contents`, {
+            params: {
+                ...reqArgs
+            }
+        });
+        return res.data;
+    }
+
+    public async getPageSubPages(id: string | number, funcArgs: BaseArgs, reqArgs?: GetPageSubPagesParams) {
+        const pageId = this.parsePageId(id);
+        const tld = getTld(this.globals, funcArgs.tld);
+        const requests = new Requests(tld, funcArgs.auth);
+
+        const res = await requests.get<GetPageSubPagesResponse>(`/pages/${pageId}/subpages`, {
+            params: {
+                ...reqArgs
+            }
+        });
+        return res.data;
+    }
+
+    public async getPageSecurity(id: string | number, funcArgs: BaseArgs, reqArgs?: GetPageSecurityParams) {
+        const pageId = this.parsePageId(id);
+        const tld = getTld(this.globals, funcArgs.tld);
+        const requests = new Requests(tld, funcArgs.auth);
+
+        const res = await requests.get<GetPageSecurityResponse>(`/pages/${pageId}/security`, {
+            params: {
+                ...reqArgs
+            }
+        });
+        return res.data;
+    }
+}

package/src/modules/requests.ts

@@ -0,0 +1,68 @@
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
+import { AuthObject } from "../types";
+
+const API_BASE_URL = '/@api/deki';
+
+export default class Requests {
+    private axiosInstance: AxiosInstance = axios.create();
+    private format: 'json' | 'xml' = 'json';
+
+    constructor(tld?: string, authObject?: AuthObject, format: 'json' | 'xml' = 'json') {
+        if (!tld) {
+            throw new Error('TLD is required');
+        }
+        if (!authObject) {
+            throw new Error('Auth object is required');
+        }
+        const parsedTLD = tld.endsWith('/') ? tld.slice(
+            0,
+            tld.length - 1
+        ) : `${tld}`;
+
+        this.format = format;
+
+        this.axiosInstance = axios.create({
+            baseURL: `${parsedTLD}${API_BASE_URL}`,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Requested-With': 'XMLHttpRequest',
+                ...authObject,
+            },
+        });
+    }
+
+    private getFormatParam() {
+        return {
+            'dream.out.format': this.format
+        }
+    }
+
+    public async get<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> {
+        return await this.axiosInstance.get<T>(url, {
+            ...config, params: {
+                ...config?.params,
+                ...this.getFormatParam()
+            }
+        });
+    }
+
+    public async post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> {
+        return await this.axiosInstance.post<T>(url, data, { ...config });
+    }
+
+    public async put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> {
+        return await this.axiosInstance.put<T>(url, data, { ...config });
+    }
+
+    public async patch<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> {
+        return await this.axiosInstance.patch<T>(url, data, { ...config });
+    }
+
+    public async del<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> {
+        return await this.axiosInstance.delete<T>(url, { ...config });
+    }
+
+    public async head<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> {
+        return await this.axiosInstance.head<T>(url, { ...config });
+    }
+}

package/src/types/auth.ts

@@ -0,0 +1,14 @@
+
+export type BrowserTokenParams = {
+    key: string;
+}
+
+export type ServerTokenParams = {
+    key: string;
+    secret: string;
+    user: string;
+}
+
+export type AuthObject = {
+    'X-Deki-Token': string | null;
+}

package/src/types/index.ts

@@ -0,0 +1,15 @@
+import { AuthObject } from './auth';
+
+export * from './auth';
+export * from './pages';
+export * from './requests';
+export * from './security';
+
+export type BaseArgs = {
+    auth: AuthObject;
+    tld?: string
+}
+
+export type ExpertGlobalOptions = {
+    tld?: string;
+}

package/src/types/pages.ts

@@ -0,0 +1,172 @@
+import { BaseQueryParams, PaginationQueryParams, RequestModeQueryParam } from "./requests";
+import { ExpertUser, PageSecurity } from "./security";
+
+export type GetPageParams = {
+    format?: 'html' | 'xhtml';
+    revision?: string;
+    include?: 'contents' | 'prevnext';
+    includeDeleted?: boolean;
+    mode?: RequestModeQueryParam
+    exclude?: string;
+} & BaseQueryParams
+
+export type GetPageContentsParams = {
+    overview?: boolean;
+    include?: string;
+    reltopath?: string;
+    relto?: number;
+    pageid?: number;
+    includes?: 'overview' | 'tags' | 'overview,tags';
+    format?: 'html' | 'xhtml' | 'text' | 'dekicode';
+    highlight?: string;
+    revision?: string;
+    mode: RequestModeQueryParam;
+    section?: string;
+} & BaseQueryParams
+
+export type GetPageSubPagesParams = BaseQueryParams & PaginationQueryParams;
+export type GetPageSecurityParams = BaseQueryParams & {
+    export?: boolean;
+}
+
+export type GetPageResponse = PageBase & PageExtended;
+export type GetPageSecurityResponse = PageSecurity;
+
+export type GetPageContentsResponse = {
+    '@revision': string;
+    '@type': string;
+    '@title': string;
+    body: string[];
+    head: string;
+    tail: string;
+}
+
+export type GetPageSubPagesResponse = {
+    '@count': string;
+    '@href': string;
+    'page.subpage': PageBase | PageBase[];
+}
+
+export type PageBase = {
+    '@id': string;
+    '@guid': string;
+    '@draft.state': string;
+    '@href': string;
+    '@deleted': string;
+    '@revision': string;
+    article: string;
+    'date.created': string;
+    'date.modified': string;
+    language: string;
+    namespace: string;
+    path: PagePath;
+    security: PageSecurity;
+    title: string;
+    'uri.ui': string;
+}
+
+export type PageExtended = {
+    '@unpublish': string;
+    aliases: {
+        [key: string]: string;
+    },
+    comments: {
+        '@count': string;
+        '@href': string;
+    },
+    contents: {
+        '@type': string;
+        '@href': string;
+        '@etag': string;
+    },
+    'contents.alt': {
+        '@type': string;
+        '@href': string;
+    },
+    'date.edited': string;
+    description: string;
+    files: {
+        '@count': string;
+        '@href': string;
+        file: PageFile | PageFile[]
+    }
+    inbound: {
+        '@count': string;
+    },
+    'language.effective': string;
+    metrics: {
+        'metric.charcount': string;
+        'metric.views': string;
+    }
+    outbound: {
+        '@count': string;
+    }
+    'page.parent': GetPageResponse;
+    'page.redirectedfrom': string;
+    properties: {
+        '@count': string;
+        '@href': string;
+        property: Record<string, string>[];
+    },
+    rating: {
+        '@score': string;
+        '@count': string;
+        '@seated.score': string;
+        '@seated.count': string;
+        '@unseated.score': string;
+        '@unseated.count': string;
+        '@anonymous.score': string;
+        '@anonymous.count': string;
+    },
+    revisions: {
+        '@count': string;
+        '@href': string;
+    },
+    subpages: {
+        '@href': string;
+    },
+    summary: string;
+    tags: {
+        '@count': string;
+        '@href': string;
+        tag: PageTag | PageTag[]
+    },
+    timeuuid: string;
+    'user.author': ExpertUser;
+    'user.createdby': ExpertUser;
+}
+
+
+export type PageFile = {
+    '@id': string;
+    '@revision': string;
+    '@res-id': string;
+    '@href': string;
+    '@res-is-head': string;
+    '@res-is-deleted': string;
+    '@res-rev-is-deleted': string;
+    '@res-contents-id': string;
+    'alt-text': string;
+    contents: object;
+    'contents.preview': any[];
+    'date.created': string;
+    'date.last-modified': string;
+    description: string;
+    filename: string;
+    revisions: object;
+    'user.createdBy': ExpertUser;
+}
+
+export type PageTag = {
+    '@value': string;
+    '@id': string;
+    '@href': string;
+    title: string;
+    type: string;
+    url: string;
+}
+
+export type PagePath = {
+    '@seo': string;
+    '#text': string;
+}

package/src/types/requests.ts

@@ -0,0 +1,11 @@
+export type BaseQueryParams = {
+    authenticate?: boolean;
+    redirects?: number;
+}
+
+export type PaginationQueryParams = {
+    offset?: number;
+    limit?: string
+}
+
+export type RequestModeQueryParam = 'edit' | 'view' | 'raw';

package/src/types/security.ts

@@ -0,0 +1,48 @@
+export type ExpertUser = {
+    '@anonymous': string;
+    '@virtual': string;
+    '@id': string;
+    '@wikiid': string;
+    '@href': string;
+    '@guid': string;
+    nick: string;
+    username: string | '#RESTRICTED'
+}
+
+export type PageSecurity = {
+    '@href': string;
+    grants: {
+        grant: SecurityGrant | SecurityGrant[]
+    },
+    'permissions.effective': SecurityGrantPermissions | SecurityGrantPermissions[]
+    'permissions.page': SecurityGrantPermissions & SecurityGrantPermissionsRestriction | SecurityGrantPermissions & SecurityGrantPermissionsRestriction[]
+    'permissions.revoked': Record<string, { operations: SecurityGrantPermissionsOperations | SecurityGrantPermissionsOperations[] }>
+}
+
+export type SecurityGrant = {
+    'date.modified': string;
+    permissions: SecurityGrantPermissions;
+    user: ExpertUser
+    'user.modifiedby': ExpertUser
+}
+
+export type SecurityGrantPermissions = {
+    operations: SecurityGrantPermissionsOperations | SecurityGrantPermissionsOperations[]
+    role: SecurityRole | SecurityRole[]
+}
+
+export type SecurityGrantPermissionsOperations = {
+    '@mask': string;
+    '#text': string;
+}
+
+export type SecurityGrantPermissionsRestriction = {
+    '@id': string;
+    '#text': string;
+}
+
+export type SecurityRole = {
+    '@id': string;
+    '@href': string;
+    '#text': string;
+}

package/src/utils.ts

@@ -0,0 +1,8 @@
+import { ExpertGlobalOptions } from "./types";
+
+export function getTld(globals: ExpertGlobalOptions, tld?: string) {
+    if (!tld && !globals.tld) {
+        throw new Error('TLD is required');
+    }
+    return tld ?? globals.tld;
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}