@codelockpro/sdk 0.0.1 → 0.1.11

package/LICENSE

@@ -0,0 +1,34 @@
+CodeLockPro SDK License
+
+Copyright (c) CodeLockPro. All rights reserved.
+
+This software (the "SDK") is proprietary to CodeLockPro and is licensed,
+not sold. Use of the SDK is permitted only in combination with an active
+CodeLockPro account in good standing.
+
+Subject to that condition, you are granted a non-exclusive,
+non-transferable, non-sublicensable, revocable license to install and
+use the SDK, and to integrate it into your own applications, solely for
+the purpose of consuming the CodeLockPro service authorised by your
+account.
+
+You may not:
+
+  1. use the SDK without an active CodeLockPro account;
+  2. use the SDK to access any service other than CodeLockPro;
+  3. sublicense, sell, rent, lease, or otherwise commercially
+     redistribute the SDK as a stand-alone product;
+  4. remove or alter any copyright, trademark, or other proprietary
+     notices contained in the SDK.
+
+The SDK 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 non-infringement. In no event
+shall CodeLockPro be liable for any claim, damages, or other liability
+arising from, out of, or in connection with the SDK or the use or other
+dealings in the SDK.
+
+This license terminates automatically if your CodeLockPro account is
+terminated, suspended, or otherwise becomes inactive. On termination
+you must cease all use of the SDK and remove all copies under your
+control.

package/README.md

@@ -0,0 +1,125 @@
+# `@codelockpro/sdk`
+
+Plain-vanilla, modular **client** SDK — the CodeLockPro client
+framework. Ships with the knowledge base as a built-in module;
+additional modules plug into the same `CodeLockPro` instance through
+the same registration surface.
+
+## Install
+
+```sh
+npm install @codelockpro/sdk
+```
+
+> **License.** The SDK is proprietary and may only be used in
+> combination with an active CodeLockPro account. See
+> [`LICENSE`](./LICENSE).
+
+## Architecture invariants
+
+1. **Modular foundation.** The core has no per-module coupling. KB is
+   just the first module registered.
+2. **Server-mediated only.** The SDK is configured with the developer's
+   own base URL. **It must never talk directly to the CodeLockPro
+   API.** The developer's server is the authoritative middle layer.
+3. **Plain vanilla.** No framework dependency. Hosts (Vue, React,
+   Next.js, plain DOM) bind their own state on top of the SDK's data,
+   events, and actions.
+
+## Usage
+
+```ts
+import { CodeLockPro } from "@codelockpro/sdk";
+
+const client = new CodeLockPro({ baseUrl: "https://example.com/my-api" });
+
+// Data
+const { articles } = await client.kb.getArticles();
+const article = await client.kb.getArticle("how-to-reset-password");
+
+// Actions
+await client.kb.trackView(article.id, { slug: article.slug });
+
+// Events (subscribe once, in any framework)
+client.on("kb.article.viewed", ({ articleId }) => {
+  console.log("viewed", articleId);
+});
+client.on("kb.search.performed", ({ query, count }) => {
+  console.log(`${count} results for ${query}`);
+});
+```
+
+`client.kb` is a convenience accessor for
+`client.module<KnowledgeBaseModule>("kb")`. The core has no
+KB-specific code path.
+
+## Registering more modules
+
+```ts
+import { CodeLockPro, ModuleContext } from "@codelockpro/sdk";
+
+function createCheckoutModule(ctx: ModuleContext) {
+  return {
+    async start(productId: string) {
+      const session = await ctx.request<{ url: string }>(
+        "/checkout/sessions",
+        { method: "POST", body: JSON.stringify({ productId }) },
+      );
+      ctx.bus.emit(`${ctx.name}.session.created`, { productId });
+      return session;
+    },
+  };
+}
+
+const client = new CodeLockPro({
+  baseUrl: "https://example.com/my-api",
+  modules: [
+    ["kb", (ctx) => /* … */],          // optional — opts out of the default
+    ["checkout", createCheckoutModule],
+  ],
+});
+
+// or after construction:
+client.register("chatbot", createChatbotModule);
+
+const checkout = client.module<{ start: (id: string) => Promise<{ url: string }> }>("checkout");
+await checkout.start("pro-monthly");
+```
+
+## Module author contract
+
+A module factory is `(ctx: ModuleContext) => MyModule`. The context
+provides:
+
+- `ctx.name`   — the registered name (`"kb"`, `"checkout"`, …)
+- `ctx.request` — HTTP helper bound to the developer's `baseUrl`
+- `ctx.bus`    — shared event bus (`on` / `off` / `emit`)
+
+Modules namespace their events as `<ctx.name>.<event>` so listeners stay
+unambiguous when many modules are registered.
+
+## Expected server-side proxy (KB)
+
+By default the KB module hits `${baseUrl}/kb/articles`,
+`${baseUrl}/kb/articles/{idOrSlug}`, `${baseUrl}/kb/categories`,
+`${baseUrl}/kb/search`, and `POST ${baseUrl}/kb/articles/{id}/views`.
+The developer's server is expected to forward those to the upstream
+CodeLockPro public read API (the PHP companion package
+`codelockpro/sdk` ships ready-made helpers for that step).
+
+## Releasing
+
+Releases are lock-stepped with the PHP package `codelockpro/sdk` —
+both packages always ship at the same version, and `sdk/js/package.json`
+is the single source of truth for the version number.
+
+To cut a release:
+
+1. Trigger the **SDK Release** workflow
+   (`.github/workflows/sdk-release.yml`) via "Run workflow".
+2. Pick `release_type`: `patch`, `minor`, or `major`.
+3. The workflow bumps `sdk/js/package.json`, commits, tags
+   `sdk-v<MAJOR.MINOR.PATCH>`, publishes `@codelockpro/sdk` to npm
+   (OIDC trusted publisher with `--provenance`), and pushes the
+   `sdk/php/` subtree to the `codelockpro-sdk-php` mirror that
+   Packagist watches.

package/dist/core/events.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function createEventBus(): EventBus;
+//# sourceMappingURL=events.d.ts.map

package/dist/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;AAE7D,MAAM,WAAW,QAAQ;IACxB,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IACrE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;CACpD;AAED,wBAAgB,cAAc,IAAI,QAAQ,CA2CzC"}

package/dist/core/events.js

@@ -0,0 +1,45 @@
+export function createEventBus() {
+    const handlers = new Map();
+    function on(event, handler) {
+        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);
+        return () => off(event, handler);
+    }
+    function off(event, handler) {
+        const set = handlers.get(event);
+        if (!set)
+            return;
+        set.delete(handler);
+        if (set.size === 0)
+            handlers.delete(event);
+    }
+    function emit(event, payload) {
+        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 };
+}
+//# sourceMappingURL=events.js.map

package/dist/core/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,cAAc;IAC7B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEtD,SAAS,EAAE,CAAI,KAAa,EAAE,OAAwB;QACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;YACV,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAuB,CAAC,CAAC;QACjC,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,SAAS,GAAG,CAAI,KAAa,EAAE,OAAwB;QACtD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,GAAG,CAAC,MAAM,CAAC,OAAuB,CAAC,CAAC;QACpC,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,SAAS,IAAI,CAAI,KAAa,EAAE,OAAW;QAC1C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QACnC,0DAA0D;QAC1D,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC;gBACJ,CAAC,CAAC,OAAO,CAAC,CAAC;YACZ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,sDAAsD;gBACtD,qDAAqD;gBACrD,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,6BAA6B,KAAK,SAAS,EAAE,GAAG,CAAC,CAAC;YACjE,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/core/module.d.ts

@@ -0,0 +1,35 @@
+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 declare class ModuleRegistry {
+    private readonly _modules;
+    register<T>(name: string, instance: T): T;
+    get<T>(name: string): T;
+    has(name: string): boolean;
+    names(): string[];
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/core/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/core/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,aAAa,KAAK,CAAC,CAAC;AAEnE;;;GAGG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAazC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAQvB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,KAAK,IAAI,MAAM,EAAE;CAGjB"}

package/dist/core/module.js

@@ -0,0 +1,33 @@
+/**
+ * Internal module registry. Exposed via :meth:`CodeLockPro.register` and
+ * :meth:`CodeLockPro.module`.
+ */
+export class ModuleRegistry {
+    constructor() {
+        this._modules = new Map();
+    }
+    register(name, instance) {
+        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(name) {
+        const mod = this._modules.get(name);
+        if (mod === undefined) {
+            throw new Error(`CodeLockPro.module: no module registered as "${name}"`);
+        }
+        return mod;
+    }
+    has(name) {
+        return this._modules.has(name);
+    }
+    names() {
+        return Array.from(this._modules.keys());
+    }
+}
+//# sourceMappingURL=module.js.map

package/dist/core/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/core/module.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,MAAM,OAAO,cAAc;IAA3B;QACkB,aAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IA8BxD,CAAC;IA5BA,QAAQ,CAAI,IAAY,EAAE,QAAW;QACpC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACd,iCAAiC,IAAI,yBAAyB,CAC9D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClC,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,GAAG,CAAI,IAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,gDAAgD,IAAI,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,GAAQ,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `@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 { EventHandler } from "./core/events.js";
+import { ModuleFactory } 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 declare class CodeLockPro {
+    readonly baseUrl: string;
+    private readonly _fetch;
+    private readonly _headers;
+    private readonly _bus;
+    private readonly _registry;
+    constructor(config: CodeLockProConfig);
+    /**
+     * 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;
+    /** Look up a previously registered module by name. */
+    module<T = unknown>(name: string): T;
+    /** Names of every currently-registered module. */
+    moduleNames(): string[];
+    /** Subscribe to an event on the shared bus. Returns an unsubscribe fn. */
+    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;
+    /**
+     * 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;
+    /** Internal HTTP helper. Modules call this rather than fetch directly so
+     * cross-cutting concerns (auth, telemetry) can be added in one place. */
+    _request<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+}
+export declare class CodeLockProApiError extends Error {
+    status: number;
+    body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+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;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAA4B,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAiB,aAAa,EAAkB,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,qBAAa,WAAW;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;gBAE/B,MAAM,EAAE,iBAAiB;IA2BrC;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC;IAUvD,sDAAsD;IACtD,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAIpC,kDAAkD;IAClD,WAAW,IAAI,MAAM,EAAE;IAIvB,0EAA0E;IAC1E,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIpE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAI/D,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI;IAInD;;;;;OAKG;IACH,IAAI,EAAE,IAAI,mBAAmB,CAE5B;IAED;6EACyE;IACnE,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;CAiB7E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC1B,MAAM,EAAE,MAAM;IAA6B,IAAI,EAAE,MAAM;gBAAvD,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAS,IAAI,EAAE,MAAM;CAI1E;AAED,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EACX,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,aAAa,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,eAAe,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,126 @@
+/**
+ * `@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 } from "./core/events.js";
+import { ModuleRegistry } from "./core/module.js";
+import { createKbModule } from "./modules/kb.js";
+export class CodeLockPro {
+    constructor(config) {
+        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 = [
+            ["kb", createKbModule],
+        ];
+        const toRegister = 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(name, factory) {
+        const ctx = {
+            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(name) {
+        return this._registry.get(name);
+    }
+    /** Names of every currently-registered module. */
+    moduleNames() {
+        return this._registry.names();
+    }
+    /** Subscribe to an event on the shared bus. Returns an unsubscribe fn. */
+    on(event, handler) {
+        return this._bus.on(event, handler);
+    }
+    off(event, handler) {
+        this._bus.off(event, handler);
+    }
+    emit(event, payload) {
+        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() {
+        return this.module("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(path, init = {}) {
+        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;
+        return (await res.json());
+    }
+}
+export class CodeLockProApiError extends Error {
+    constructor(status, statusText, body) {
+        super(`CodeLockPro API ${status} ${statusText}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "CodeLockProApiError";
+    }
+}
+export { createKbModule };
+export default CodeLockPro;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/modules/kb.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 { 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 {
+    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[];
+    }>;
+    /**
+     * 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>;
+    /** 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;
+}
+/**
+ * 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 declare const createKbModule: ModuleFactory<KnowledgeBaseModule>;
+/** Variant that accepts module-specific options (e.g. a custom basePath). */
+export declare function createKbModuleWith(options: KbModuleOptions): ModuleFactory<KnowledgeBaseModule>;
+//# sourceMappingURL=kb.d.ts.map