@codelockpro/sdk 0.0.1 → 0.1.11

package/dist/modules/kb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb.d.ts","sourceRoot":"","sources":["../../src/modules/kb.ts"],"names":[],"mappings":"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"}

package/dist/modules/kb.js

@@ -0,0 +1,86 @@
+function _qs(params) {
+    const usp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        usp.set(k, String(v));
+    }
+    const s = usp.toString();
+    return s ? `?${s}` : "";
+}
+/**
+ * Module factory. Conforms to {@link ModuleFactory} — the SDK core treats
+ * KB exactly like any other module.
+ *
+ *     const client = new CodeLockPro({
+ *       baseUrl: "https://example.com/my-api",
+ *       modules: [["kb", createKbModule]],
+ *     });
+ */
+export const createKbModule = (ctx) => {
+    return _create(ctx, {});
+};
+/** Variant that accepts module-specific options (e.g. a custom basePath). */
+export function createKbModuleWith(options) {
+    return (ctx) => _create(ctx, options);
+}
+function _create(ctx, options) {
+    const base = (options.basePath ?? "/kb").replace(/\/+$/, "");
+    const ns = ctx.name; // "kb" by convention; whatever the host registered as.
+    function _ev(name) {
+        return `${ns}.${name}`;
+    }
+    return {
+        async getArticles(opts = {}) {
+            const qs = _qs({
+                category_id: opts.categoryId,
+                category_slug: opts.categorySlug,
+                limit: opts.limit,
+                starting_after: opts.startingAfter,
+            });
+            return ctx.request(`${base}/articles${qs}`);
+        },
+        async getArticle(idOrSlug) {
+            if (typeof idOrSlug !== "string" || idOrSlug.length === 0) {
+                return Promise.reject(new Error("getArticle: idOrSlug required"));
+            }
+            return ctx.request(`${base}/articles/${encodeURIComponent(idOrSlug)}`);
+        },
+        async getCategories() {
+            return ctx.request(`${base}/categories`);
+        },
+        async search(query, limit) {
+            const result = await ctx.request(`${base}/search${_qs({ q: query, limit })}`);
+            ctx.bus.emit(_ev("search.performed"), {
+                query,
+                count: Array.isArray(result?.articles) ? result.articles.length : 0,
+            });
+            return result;
+        },
+        async trackView(articleId, opts = {}) {
+            if (typeof articleId !== "string" || articleId.length === 0) {
+                throw new Error("trackView: articleId required");
+            }
+            // Bus event fires synchronously so host apps update immediately.
+            ctx.bus.emit(_ev("article.viewed"), {
+                articleId,
+                slug: opts.slug,
+            });
+            // Fire-and-forget on the wire: do **not** await, so rendering
+            // is never blocked, and swallow errors so view-tracking is
+            // never user-visible.
+            void ctx
+                .request(`${base}/articles/${encodeURIComponent(articleId)}/track-view`, { method: "POST" })
+                .catch(() => {
+                /* swallow — see docstring */
+            });
+        },
+        on(event, handler) {
+            return ctx.bus.on(_ev(event), handler);
+        },
+        off(event, handler) {
+            ctx.bus.off(_ev(event), handler);
+        },
+    };
+}
+//# sourceMappingURL=kb.js.map

package/dist/modules/kb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb.js","sourceRoot":"","sources":["../../src/modules/kb.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,46 @@
 {
-  "name": "@codelockpro/sdk",
-  "version": "0.0.1",
-  "private": false
+	"name": "@codelockpro/sdk",
+	"version": "0.1.11",
+	"description": "Framework-agnostic, modular client SDK for CodeLockPro. Module one: Knowledge base. Configured with the developer's own base URL — never communicates directly with the CodeLockPro API.",
+	"license": "SEE LICENSE IN LICENSE",
+	"homepage": "https://github.com/mbos01/codelockpro/tree/main/sdk/js#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mbos01/codelockpro.git",
+		"directory": "sdk/js"
+	},
+	"bugs": {
+		"url": "https://github.com/mbos01/codelockpro/issues"
+	},
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"test": "node --test"
+	},
+	"keywords": [
+		"codelockpro",
+		"sdk",
+		"knowledge-base",
+		"licensing"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"sideEffects": false
 }
-

package/src/core/events.ts

@@ -0,0 +1,65 @@
+/**
+ * Tiny synchronous event bus shared by all SDK modules.
+ *
+ * The bus is intentionally minimal — no priority, no async fan-out, no
+ * wildcard subscriptions — because the SDK is a thin data/action layer
+ * that the host app (Vue, React, Next.js, plain DOM) decorates with its
+ * own state-management primitives. Modules emit semantic namespaced
+ * events (e.g. ``kb.article.viewed``) and host code subscribes via
+ * :meth:`CodeLockPro.on`.
+ *
+ * The bus has no awareness of which module emits what — it is a
+ * module-agnostic primitive owned by the core.
+ */
+export type EventHandler<T = unknown> = (payload: T) => void;
+
+export interface EventBus {
+	on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+	off<T = unknown>(event: string, handler: EventHandler<T>): void;
+	emit<T = unknown>(event: string, payload?: T): void;
+}
+
+export function createEventBus(): EventBus {
+	const handlers = new Map<string, Set<EventHandler>>();
+
+	function on<T>(event: string, handler: EventHandler<T>): () => void {
+		if (typeof event !== "string" || event.length === 0) {
+			throw new Error("CodeLockPro.on: event name is required");
+		}
+		if (typeof handler !== "function") {
+			throw new Error("CodeLockPro.on: handler must be a function");
+		}
+		let set = handlers.get(event);
+		if (!set) {
+			set = new Set();
+			handlers.set(event, set);
+		}
+		set.add(handler as EventHandler);
+		return () => off(event, handler);
+	}
+
+	function off<T>(event: string, handler: EventHandler<T>): void {
+		const set = handlers.get(event);
+		if (!set) return;
+		set.delete(handler as EventHandler);
+		if (set.size === 0) handlers.delete(event);
+	}
+
+	function emit<T>(event: string, payload?: T): void {
+		const set = handlers.get(event);
+		if (!set || set.size === 0) return;
+		// Snapshot so handlers may unsubscribe themselves safely.
+		for (const h of Array.from(set)) {
+			try {
+				h(payload);
+			} catch (err) {
+				// Never let one handler break another. Surface to the
+				// host via ``console.error`` rather than swallowing.
+				// eslint-disable-next-line no-console
+				console.error(`CodeLockPro: handler for "${event}" threw`, err);
+			}
+		}
+	}
+
+	return { on, off, emit };
+}

package/src/core/module.ts

@@ -0,0 +1,62 @@
+import { EventBus } from "./events.js";
+
+/**
+ * Module contract.
+ *
+ * A module is anything the host code wants to attach to a
+ * :class:`CodeLockPro` instance. The core does not know about any
+ * specific module; modules are produced by user-supplied factories.
+ *
+ * A factory receives the {@link ModuleContext} and returns the
+ * module's public surface (an object). The shape is entirely up to the
+ * module author — by convention it exposes data accessors
+ * (``getArticles``), actions (``trackView``), and emits semantic
+ * events on the shared bus.
+ */
+export interface ModuleContext {
+	/** Module name as registered (e.g. ``"kb"``). */
+	readonly name: string;
+	/** HTTP helper bound to the developer's own ``baseUrl``. */
+	request<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+	/** Shared event bus. Modules namespace their events as ``"<name>.…"``. */
+	readonly bus: EventBus;
+}
+
+export type ModuleFactory<T = unknown> = (ctx: ModuleContext) => T;
+
+/**
+ * Internal module registry. Exposed via :meth:`CodeLockPro.register` and
+ * :meth:`CodeLockPro.module`.
+ */
+export class ModuleRegistry {
+	private readonly _modules = new Map<string, unknown>();
+
+	register<T>(name: string, instance: T): T {
+		if (typeof name !== "string" || name.length === 0) {
+			throw new Error("CodeLockPro.register: module name is required");
+		}
+		if (this._modules.has(name)) {
+			throw new Error(
+				`CodeLockPro.register: module "${name}" is already registered`,
+			);
+		}
+		this._modules.set(name, instance);
+		return instance;
+	}
+
+	get<T>(name: string): T {
+		const mod = this._modules.get(name);
+		if (mod === undefined) {
+			throw new Error(`CodeLockPro.module: no module registered as "${name}"`);
+		}
+		return mod as T;
+	}
+
+	has(name: string): boolean {
+		return this._modules.has(name);
+	}
+
+	names(): string[] {
+		return Array.from(this._modules.keys());
+	}
+}

package/src/index.ts

@@ -0,0 +1,182 @@
+/**
+ * `@codelockpro/sdk` — the CodeLockPro client framework.
+ *
+ * A generic, modular foundation developers use to build a complete
+ * user experience on their own site by composing CodeLockPro modules.
+ * The package ships with a single built-in module (``kb`` — knowledge
+ * base) and exposes the same registration surface for any additional
+ * modules the developer authors or that ship in future package
+ * versions.
+ *
+ * The core in this file has no knowledge of any specific module.
+ * Modules are attached at construction time (or later via
+ * :meth:`register`) and are looked up by name through :meth:`module`.
+ * Each module gets a shared {@link EventBus} and an HTTP helper bound
+ * to the developer's own backend URL.
+ *
+ * Architecture invariants (see /docs/sdk/README.md):
+ *
+ *   1. **Modular foundation.** No coupling to any specific module.
+ *   2. **Server-mediated access only.** The client SDK is configured
+ *      with the developer's *own* base URL. It must never talk
+ *      directly to the CodeLockPro API.
+ *   3. **Plain vanilla.** No framework binding. Hosts (Vue / React /
+ *      Next.js / plain DOM) bind their own state on top of the SDK's
+ *      data, events, and actions.
+ */
+import { createEventBus, EventBus, EventHandler } from "./core/events.js";
+import { ModuleContext, ModuleFactory, ModuleRegistry } from "./core/module.js";
+import { createKbModule, KnowledgeBaseModule } from "./modules/kb.js";
+
+export interface CodeLockProConfig {
+	/**
+	 * Base URL of the developer's own backend, e.g.
+	 * ``https://example.com/my-api``. Module paths are appended to it
+	 * (``/kb/articles`` etc.). Direct access to ``https://api.codelock.pro``
+	 * is intentionally not supported — see invariant #2.
+	 */
+	baseUrl: string;
+	/**
+	 * Modules to register at construction time. Use ``false`` to skip the
+	 * default registration (KB) and register everything explicitly via
+	 * :meth:`register`.
+	 *
+	 * Each entry is a ``[name, factory]`` tuple — exactly the same shape
+	 * the registry uses internally — so the same surface registers any
+	 * future module the same way as KB:
+	 *
+	 *     new CodeLockPro({
+	 *       baseUrl: "…",
+	 *       modules: [
+	 *         ["kb", createKbModule],
+	 *         ["checkout", createCheckoutModule],
+	 *       ],
+	 *     });
+	 */
+	modules?: false | Array<[string, ModuleFactory<unknown>]>;
+	/** Optional fetch implementation override (tests / Node 16). */
+	fetch?: typeof fetch;
+	/** Optional default headers merged into every request. */
+	headers?: Record<string, string>;
+}
+
+export class CodeLockPro {
+	readonly baseUrl: string;
+	private readonly _fetch: typeof fetch;
+	private readonly _headers: Record<string, string>;
+	private readonly _bus: EventBus;
+	private readonly _registry: ModuleRegistry;
+
+	constructor(config: CodeLockProConfig) {
+		if (!config || typeof config.baseUrl !== "string" || !config.baseUrl) {
+			throw new Error("CodeLockPro: baseUrl is required");
+		}
+		this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this._fetch = config.fetch ?? globalThis.fetch;
+		this._headers = config.headers ?? {};
+		if (typeof this._fetch !== "function") {
+			throw new Error("CodeLockPro: no fetch implementation available");
+		}
+		this._bus = createEventBus();
+		this._registry = new ModuleRegistry();
+
+		// Default registration: KB is module one. Pass ``modules: false``
+		// (or override with an explicit list) to opt out — the core
+		// itself has no knowledge-base coupling.
+		const defaultModules: Array<[string, ModuleFactory<unknown>]> = [
+			["kb", createKbModule],
+		];
+		const toRegister: Array<[string, ModuleFactory<unknown>]> =
+			config.modules === false ? [] : config.modules ?? defaultModules;
+
+		for (const [name, factory] of toRegister) {
+			this.register(name, factory);
+		}
+	}
+
+	/**
+	 * Register a module after construction. Modules can be defined by
+	 * any caller — KB, future first-party modules, and even host-app
+	 * extensions all use the same entry point.
+	 */
+	register<T>(name: string, factory: ModuleFactory<T>): T {
+		const ctx: ModuleContext = {
+			name,
+			request: this._request.bind(this),
+			bus: this._bus,
+		};
+		const instance = factory(ctx);
+		return this._registry.register(name, instance);
+	}
+
+	/** Look up a previously registered module by name. */
+	module<T = unknown>(name: string): T {
+		return this._registry.get<T>(name);
+	}
+
+	/** Names of every currently-registered module. */
+	moduleNames(): string[] {
+		return this._registry.names();
+	}
+
+	/** Subscribe to an event on the shared bus. Returns an unsubscribe fn. */
+	on<T = unknown>(event: string, handler: EventHandler<T>): () => void {
+		return this._bus.on(event, handler);
+	}
+
+	off<T = unknown>(event: string, handler: EventHandler<T>): void {
+		this._bus.off(event, handler);
+	}
+
+	emit<T = unknown>(event: string, payload?: T): void {
+		this._bus.emit(event, payload);
+	}
+
+	/**
+	 * Convenience accessor for the knowledge-base module. Equivalent to
+	 * ``client.module<KnowledgeBaseModule>("kb")``. Provided as ergonomic
+	 * sugar so existing call sites read naturally; it is not part of the
+	 * core's invariants — if KB is unregistered this throws.
+	 */
+	get kb(): KnowledgeBaseModule {
+		return this.module<KnowledgeBaseModule>("kb");
+	}
+
+	/** Internal HTTP helper. Modules call this rather than fetch directly so
+	 * cross-cutting concerns (auth, telemetry) can be added in one place. */
+	async _request<T = unknown>(path: string, init: RequestInit = {}): Promise<T> {
+		const url = `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+		const res = await this._fetch(url, {
+			...init,
+			headers: {
+				Accept: "application/json",
+				...this._headers,
+				...(init.headers || {}),
+			},
+		});
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new CodeLockProApiError(res.status, res.statusText, text);
+		}
+		if (res.status === 204) return undefined as T;
+		return (await res.json()) as T;
+	}
+}
+
+export class CodeLockProApiError extends Error {
+	constructor(public status: number, statusText: string, public body: string) {
+		super(`CodeLockPro API ${status} ${statusText}: ${body}`);
+		this.name = "CodeLockProApiError";
+	}
+}
+
+export type { EventBus, EventHandler } from "./core/events.js";
+export type { ModuleContext, ModuleFactory } from "./core/module.js";
+export type {
+	KnowledgeBaseModule,
+	KbArticle,
+	KbCategory,
+	KbListOptions,
+} from "./modules/kb.js";
+export { createKbModule };
+export default CodeLockPro;

package/src/modules/kb.ts

@@ -0,0 +1,205 @@
+/**
+ * Knowledge base — the built-in module of the CodeLockPro SDK.
+ *
+ * Wraps the developer's server-side proxy of the unauthenticated public
+ * KB endpoints. This module is **not** privileged inside the SDK core —
+ * it uses the same {@link ModuleFactory} contract any additional
+ * module the developer registers will use.
+ *
+ * Default expected paths under the configured ``baseUrl`` (override via
+ * ``options.basePath`` if your proxy mounts elsewhere):
+ *
+ *   GET  {basePath}/articles                          → list articles
+ *   GET  {basePath}/articles/{idOrSlug}               → single article
+ *   GET  {basePath}/categories                        → list categories
+ *   GET  {basePath}/search?q=…                        → full-text search
+ *   POST {basePath}/articles/{id}/track-view          → record a view (action)
+ *
+ * Events emitted on the shared bus (subscribe via ``client.on(...)``):
+ *
+ *   ``kb.article.viewed``  — payload ``{ articleId: string, slug?: string }``
+ *   ``kb.search.performed`` — payload ``{ query: string, count: number }``
+ *
+ * Custom events from host apps may follow the same ``kb.*`` namespace.
+ */
+import type { ModuleContext, ModuleFactory } from "../core/module.js";
+
+export interface KbArticle {
+	id: string;
+	application_id: string;
+	category_id: string | null;
+	developer_id: string;
+	slug: string;
+	title: string;
+	excerpt: string | null;
+	content?: string;
+	status: "draft" | "published";
+	published_at: string | null;
+	created_at: string | null;
+	updated_at: string | null;
+}
+
+export interface KbCategory {
+	id: string;
+	application_id: string;
+	developer_id: string;
+	name: string;
+	slug: string;
+	description: string | null;
+	created_at: string | null;
+	updated_at: string | null;
+}
+
+export interface KbListOptions {
+	categoryId?: string;
+	categorySlug?: string;
+	limit?: number;
+	startingAfter?: string;
+}
+
+export interface KbArticleViewedPayload {
+	articleId: string;
+	slug?: string;
+}
+
+export interface KbSearchPerformedPayload {
+	query: string;
+	count: number;
+}
+
+export interface KnowledgeBaseModule {
+	// --- data accessors ----------------------------------------------------
+	getArticles(opts?: KbListOptions): Promise<{ articles: KbArticle[] }>;
+	getArticle(idOrSlug: string): Promise<KbArticle>;
+	getCategories(): Promise<{ categories: KbCategory[] }>;
+	search(
+		query: string,
+		limit?: number,
+	): Promise<{ query: string; articles: KbArticle[] }>;
+
+	// --- actions -----------------------------------------------------------
+	/**
+	 * Record a view of an article via the developer's proxy and emit
+	 * ``kb.article.viewed`` on the shared event bus. Errors from the
+	 * server are swallowed so view-tracking never blocks rendering;
+	 * the bus event always fires.
+	 */
+	trackView(articleId: string, opts?: { slug?: string }): Promise<void>;
+
+	// --- events ------------------------------------------------------------
+	/** Subscribe to an event scoped to this module (``kb.<event>``). */
+	on<T = unknown>(event: string, handler: (payload: T) => void): () => void;
+	off<T = unknown>(event: string, handler: (payload: T) => void): void;
+}
+
+export interface KbModuleOptions {
+	/** Override the proxy mount-point (default: ``/kb``). */
+	basePath?: string;
+}
+
+function _qs(params: Record<string, unknown>): string {
+	const usp = new URLSearchParams();
+	for (const [k, v] of Object.entries(params)) {
+		if (v === undefined || v === null || v === "") continue;
+		usp.set(k, String(v));
+	}
+	const s = usp.toString();
+	return s ? `?${s}` : "";
+}
+
+/**
+ * Module factory. Conforms to {@link ModuleFactory} — the SDK core treats
+ * KB exactly like any other module.
+ *
+ *     const client = new CodeLockPro({
+ *       baseUrl: "https://example.com/my-api",
+ *       modules: [["kb", createKbModule]],
+ *     });
+ */
+export const createKbModule: ModuleFactory<KnowledgeBaseModule> = (
+	ctx: ModuleContext,
+): KnowledgeBaseModule => {
+	return _create(ctx, {});
+};
+
+/** Variant that accepts module-specific options (e.g. a custom basePath). */
+export function createKbModuleWith(
+	options: KbModuleOptions,
+): ModuleFactory<KnowledgeBaseModule> {
+	return (ctx) => _create(ctx, options);
+}
+
+function _create(
+	ctx: ModuleContext,
+	options: KbModuleOptions,
+): KnowledgeBaseModule {
+	const base = (options.basePath ?? "/kb").replace(/\/+$/, "");
+	const ns = ctx.name; // "kb" by convention; whatever the host registered as.
+
+	function _ev(name: string): string {
+		return `${ns}.${name}`;
+	}
+
+	return {
+		async getArticles(opts: KbListOptions = {}) {
+			const qs = _qs({
+				category_id: opts.categoryId,
+				category_slug: opts.categorySlug,
+				limit: opts.limit,
+				starting_after: opts.startingAfter,
+			});
+			return ctx.request(`${base}/articles${qs}`);
+		},
+
+		async getArticle(idOrSlug: string) {
+			if (typeof idOrSlug !== "string" || idOrSlug.length === 0) {
+				return Promise.reject(new Error("getArticle: idOrSlug required"));
+			}
+			return ctx.request(`${base}/articles/${encodeURIComponent(idOrSlug)}`);
+		},
+
+		async getCategories() {
+			return ctx.request(`${base}/categories`);
+		},
+
+		async search(query: string, limit?: number) {
+			const result = await ctx.request<{ query: string; articles: KbArticle[] }>(
+				`${base}/search${_qs({ q: query, limit })}`,
+			);
+			ctx.bus.emit<KbSearchPerformedPayload>(_ev("search.performed"), {
+				query,
+				count: Array.isArray(result?.articles) ? result.articles.length : 0,
+			});
+			return result;
+		},
+
+		async trackView(articleId: string, opts: { slug?: string } = {}) {
+			if (typeof articleId !== "string" || articleId.length === 0) {
+				throw new Error("trackView: articleId required");
+			}
+			// Bus event fires synchronously so host apps update immediately.
+			ctx.bus.emit<KbArticleViewedPayload>(_ev("article.viewed"), {
+				articleId,
+				slug: opts.slug,
+			});
+			// Fire-and-forget on the wire: do **not** await, so rendering
+			// is never blocked, and swallow errors so view-tracking is
+			// never user-visible.
+			void ctx
+				.request(
+					`${base}/articles/${encodeURIComponent(articleId)}/track-view`,
+					{ method: "POST" },
+				)
+				.catch(() => {
+					/* swallow — see docstring */
+				});
+		},
+
+		on<T = unknown>(event: string, handler: (payload: T) => void): () => void {
+			return ctx.bus.on<T>(_ev(event), handler);
+		},
+		off<T = unknown>(event: string, handler: (payload: T) => void): void {
+			ctx.bus.off<T>(_ev(event), handler);
+		},
+	};
+}