@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

npm install @codelockpro/sdk

License. The SDK is proprietary and may only be used in combination with an active CodeLockPro account. See 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

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.

Portal/community module naming

For forum integrations, portal is now the canonical JS SDK module surface:

import { createPortalModule } from "@codelockpro/sdk/portal";
client.register("portal", createPortalModule);

Backward-compatible community aliases remain available:

import { createCommunityModule } from "@codelockpro/sdk/community";
client.register("community", createCommunityModule);

Migration notes for integrators:

• JS module surface: migrate community imports/registration to @codelockpro/sdk/portal, createPortalModule, and client.portal().
• Event namespaces: prefer portal.thread.created, portal.post.created, portal.thread.flagged, portal.post.flagged. Keep community.* listeners only while older integrations are still registered as community.
• Routes/endpoints: forum traffic should target portal naming consistently (/portal/* proxy routes, upstream /v1/portal/forum/* endpoints).
• Compatibility window: community naming remains supported for the current 0.x SDK line and will only be removed in a future major release with advance notice.

Registering more modules

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.